Doc: unclear how to make items available

[gallardo]

I'm trying to build some test for one style that I have renamed. I cannot make sense of this quote:

To make items available for a given style, join the group and create a top-level collection with the slug name of the style, and add some items to the collection. It is helpful to write a short description of the item to be tests (i.e. within 30 characters or so) into the Abstract field.

What I've done:

1.Cloned https://github.com/citation-style-language/styles.git, created copy of apa.csl as apa-test.csl 2.Edited apa-test.csl to rename its id to http://www.zotero.org/styles/apa-test 3.Forked and cloned https://github.com/Juris-M/jm-style-tests as per instructions 4.Edited ~/.cslrun.yaml as per instructions 5.Changed working dir into the cloned jm-style-test 6.Run cslrun:

$cslrun -w /home/my-user/src/styles/apa-test.csl -U
# No collection found for style "apa-test" in library of test items.
# To start building tests for this style, follow the instructions in the
# Citeproc Test Runner README:
#     https://www.npmjs.com/package/citeproc-test-runner

7.Tried copying jm-style-tests/apa into jm-style-tests/apa-test doesn't make any difference

[gallardo]

After several hours fiddling with the tools and config, I found what I was looking for: I only need to locally test some details of the APA style. Below are the instructions I miss. I could file a PR, but I guess @fbennett prefers to update the doc himself?

How to create a test for a style with slug name my-style

• Prepare a rough copy of the style (if it resembles another style, you might just fetch a copy of that, and change its title and ID);
• Prepare a small collection of items in Zotero for use in testing the style, and export the full set of items to a file, in CSL JSON format.
• For convenience, if you haven't yet, clone the style-test directory

  $ git clone https://github.com/my-github-name/jm-style-tests.git

• And cd into it

  $ cd  jm-style-tests

• Create a subdirectory for testing your style. The name must match the slug name

  $ mkdir my-style

• Create a test file. The easiest way is copying and editing an existing one

  $ cp apa/style_test001.txt my-style/style_test001.txt

• Replace the content of the INPUT section with the content of your previously created collections of items in CSL format
• Edit your ~/.cslrun.yaml to point to the jm-style-test dir

  groupID: 2319948
  path:
  styletests: /path/to/jm-style-tests/

• Invoke cslrun to adopt the current style output as the RESULT and accept with y

  
  $ cslrun -w /path/to/my-style.csl -s style_test001
  Using processor from package
  Watching: /path/to/my-style.csl
  Validating CSL.
  Testing CSL.
  
  -------------------------------------------------------
  ⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅✈
  -------------------------------------------------------
  
  0 passing (388ms)
  1 failing
  
  1) Integration tests
    should pass test style_test001 style_test001:
  
    AssertionError: /path/to/jm-style-tests/my-style/style_test001.txt
    + expected - actual
  [...]

Adopt this output as correct test RESULT? (y/n)

- Edit the `RESULT` section of the modified test `my-style/style_test001.txt` to your like and retest

$ cslrun -w /path/to/my-style.csl -s style_test001

## Notes

You can execute the single test `style_test001.txt` for your `my-style`:

$ cslrun -w /path/to/my-style.csl -s style_test001

Or all tests `style_*.txt`:

$ cslrun -w /path/to/my-style.csl -g style

Invoking `cslrun` with all tests (`-a`) requires correct configuration of parameters `local` and `std` in `~/.cslrun.yaml`

[fbennett]

Many thanks for this, and apologies for not responding sooner. I had started on a revision, but your rev is more likely to be cprehensive. Just woke up here, will review today and get back if I have any questions.

[gallardo]

No reasons to apologize. Thanks for your great job, and I'm glad if this helps.