Testing

Testing of rsonpath is how we satisfy the core I. Correctness principle, but is a complicated affair due to how the engines are structured – they're basically big state machines with not many units to unit test. We currently rely on end-to-end tests of entire JSON documents and queries, but the work to improve that is ongoing, see area: reliability.

One of the more interesting kinds of tests we have are proptests, see TODO.

There are three categories of tests.

Unit Tests

These are currently rather scarce. We use test-case to make data-driven testing easier, and pretty_assertions for better test failure display.

• DO add unit tests for each new features.
• DO use just t to verify all unit tests pass.
• DO put unit tests in separate submodules marked with #[cfg(test)] within the file the unit it tests is contained.
• DO import use pretty_assertions::* in the test module to use better assertion diffs by default.
• DO NOT test complex scenarios with multiple modules in a unit test; for example, don't test the compiler by first using the parser to parse a query string and then compile the output, that tests both the parser and the compiler at the same time and is not a unit test – construct a query by hand and pass it to the compiler instead.

Doc Tests

Every part of the library that is publicly visible should have doctests. These are the hardest to maintain, since IDEs don't actually compile them or rename items within them. Add Use just test-doc to make sure they work.

• DO add an Examples section to every new public surface area, except for really trivial stuff like getter functions.
• DO use just t or just test-doc to verify all doc tests pass.
• DO hide irrelevant imports from the tests by prefixing them with #.

Integration Tests

When testing more complicated scenarios between a handful of units, we use Rust's integration testing help (even if a better name for a particular test case would be component or end-to-end tests). An example is testing the structural classification, which by necessity also requires quote classification to behave correctly. These tests are located externally to the crate's source, in the /crates/rsonpath-lib/tests directory, and use the lib's public API just like an external consumer would.

Currently we have two suites, the engine_correctness_test and classifier_correctness_tests. The first is our E2E suite with a dedicated wiki page; the latter tests some known complicated inputs for classification and also has proptests to fuzz the classifier.

• DO add appropriate tests to the engine_correctness_test suite when changing the engine's behaviour, fixing a bug, or adding a new feature; see the page linked above for details.
• DO NOT use integration tests for small localized tests, use unit tests instead.