Module tests

[fbennett]

[from decommissioned csl-validator.js fork]

Modules should be associated with integration test fixtures, so that their behavior can be easily illustrated, and confirmed during review. For Zotero translators, tests are embedded in the translators themselves; a similar approach can be adopted in Juris-M style modules.

We would start with comprehensive sample text for each Juris-M item type. In casting a test, the module author would select the fields to be included in the test fixture. When approved, a record of the fields to be used and the (XML-escaped) expected output would be added to the module, and travel with it.

[fbennett]

With a standard set of variable values, the fields to be included in a test fixture can be expressed concisely as a parameter string, accompanied by the current style output and a flag to show if it's passing or failing on human review. Something like:

<tests>
   <test parameters="310410010200101001">Smith et al., "On Time and Place," 1977</test>
</tests>

The standard field data will need to be rigidly organized. It can be documented in reST, and a custom renderer can dump the JS needed for the test platform. The text of the reST can be pegged at a version increment, so that a style pulls the correct data for its level.

[cormacrelf]

Hey Frank. I wrote one, https://github.com/cormacrelf/jest-csl/. I didn't see this issue, but now that I have, I wouldn't say all that configuration complexity is necessary. The duality of tests as specifications/documentation as well as being tests is not well served by using a rigid set of standard variable values. Instead, slamming any test input into citeproc-js is fine, and since you can put anything in there, you can use recognizable examples and carry it through to generated documentation for using the CSL under test.

(Aside: I actually came here searching for how you produce the field mappings in the Style Development editor. There's that weird custom-compressed src/fields.json (GZIP would probably do a better job than numeric back-references, but OK), but how did you produce that? Is that the canonical copy? Is there one for plain Zotero? I'm trying write a CSL-JSON -> tutorial for how to enter this item in your reference manager } function.)

Here's a sneak preview of the generated, interactive documentation based on the test suite I'm currently writing (and yes, there is a bug in my getAbbreviation implementation):