citeproc-test-runner/README.md

CSL test runner with style support

[Citeproc Test Runner](https://www.npmjs.com/package/citeproc-test-runner) (CTR for short) is a productivity tool for maintaining citation styles in the popular [Citation Style Language](https://citationstyles.org/) (CSL) used by [Zotero](https://www.zotero.org/), [Mendeley](https://www.mendeley.com/), [Jurism](https://juris-m.github.io/) and other projects. The script assumes that [node](https://nodejs.org/), [java](https://www.java.com/en/download/) and [mocha](https://mochajs.org/) are installed (the last globally with `npm i -g mocha`). With those in place, installation is a one-liner:
``` bash
    npm install -g citeproc-test-runner
```

After installation, starting the program with `cslrun` will spit out instructions pointing back to this document. The remaining steps for setup are explained below. The instructions assume that you have a GitHub account (if you don't yet have an account, you should [create a free account now](https://github.com)).

## Setting up

### Joining the test items library

CTR can build tests for individual styles, using items from a shared public library. As a first step, visit the "Jurism Test Submissions" library (below), join it, and then sync Jurism or Zotero to add the library to your local client:

```bash
    https://www.zotero.org/groups/2339078/jurism_test_submissions
```

**Note:** Earlier versions of ``cslrun`` were set to use a different library. 

### Adding a collection of style items

Tests are identified to a style using its *slug name*, which is the last portion of the style's CSL `id` string. For example, the slug name of the style `http://www.zotero.org/styles/cell` is `cell`. 

Tests are written into and run from a local *style tests directory*. To facilitate the sharing of tests among maintainers, this directory should be a clone of *your personal fork* of the [jm-style-tests](https://github.com/Juris-M/jm-style-tests) repository on GitHub:
```bash
    <visit https://github.com/Juris-M/jm-style-tests and fork the repository>
    git clone https://github.com/my-github-name/jm-style-tests.git
```



This allows style maintainers to quickly confirm that changes subsequently made to the style do not have unwanted side effects.



After cloning your fork of the tests repository, set the path to it in the CTR configuration file, located in the user home directory `~/.cslrun.yaml`:
```yaml
groupID: 2319948
path:
  styletests: /path/to/jm-style-tests
  local: false
  std: false
  src: false
  locale: false
  modules: false
  cslschema: false
  cslmschema: false
```

By default, CTR builds tests from [Jurism Style Test Items](https://www.zotero.org/groups/2319948/jurism_style_test_items?), a public group library (to use a different source library, set its `id` as the `groupID` value in `~/.cslrun.yaml`). 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.

To build tests, use `cslrun` with the `-w` option to set the style to be tested, and the `-U` option to update test fixtures from the group library:
```bash
    cslrun -w /path/to/cell.csl -U
```

This will write test fixtures to a subdirectory of the style tests directory, named for the slug name of the style (if the subdirectory does not exist, it will be created). Finish the tests by using `cslrun` with the `a` option to run all tests, and the `-k` option to confirm output:
```bash
    cslrun -w /path/to/cell.csl -a -k
```

With the `-k` option, `cslrun` will show the style output as a failed test, prompting for confirmation that the output is correct. If `Y` is selected for each failing fixture, all tests will pass. Use `ctrl-c` to exit `cslrun` and return to the command line.

To share the tests. check them in and push them to your `jm-style-tests` repository on GitHub:
```bash
    cd /path/to/jm-style-tests
    git commit -m "Add tests for cell" -a
    git push
```

Then jump to GitHub and file a pull request to the main `jm-style-tests` project to have your tests added to the suite.

That's pretty much it. You can rerun the tests against the style anytime. If the `-k` option is omitted, `cslrun` will simply watch the CSL file, revalidating it and rerunning all tests whenever it is saved, to convert any plain text editor into a poorman's CSL IDE:
```bash
    cslrun -w /path/to/cell.csl -a
```

A few other options are available on CTR. See `cslrun -h` for further details.

## Test layout

CTR works from tests written in the idiosyncratic CSL test format,
documented in the
[CSL test-suite repository](https://github.com/citation-style-language/test-suite/blob/10f19d651202290d163662573f5897f768b51c4a/README.rst).
The description there is for the self-contained tests used in the processor
test suite, and the tests generated by CTR (see below) differ in a few respects.
Specifically: CTR style tests omit the CSL section (because they use CSL code directly
from the style); they include a KEYS array to memo the source of the input data; and
they use a MODE of "all" to exercise the various forms that a citation may have
in all contexts.

-------------------------------

Enjoy!

FB