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.