1# The `rustdoc-json` test suite23This page is specifically about the test suite named `rustdoc-json`, which tests rustdoc's [json output].4For other test suites used for testing rustdoc, see [§Rustdoc test suites](../tests/compiletest.md#rustdoc-test-suites).56Tests are run with compiletest, and have access to the usual set of [directives](../tests/directives.md).7Frequently used directives here are:89- [`//@ aux-build`][aux-build] to have dependencies.10- `//@ edition: 2021` (or some other edition).11- `//@ compile-flags: --document-hidden-items` to enable [document private items].1213Each crate's json output is checked by 2 programs: [jsondoclint](#jsondocck) and [jsondocck](#jsondocck).1415## jsondoclint1617[jsondoclint] checks that all [`Id`]s exist in the `index` (or `paths`).18This makes sure there are no dangling [`Id`]s.1920<!-- TODO: It does some more things too?21Also, talk about how it works22 -->2324## jsondocck2526[jsondocck] processes directives given in comments, to assert that the values in the output are expected.27It's a lot like [htmldocck](./rustdoc-html-test-suite.md) in that way.2829It uses [JSONPath] as a query language, which takes a path, and returns a *list* of values that that path is said to match to.3031### Directives3233- `//@ has <path>`: Checks `<path>` exists, i.e. matches at least 1 value.34- `//@ !has <path>`: Checks `<path>` doesn't exist, i.e. matches 0 values.35- `//@ has <path> <value>`: Check `<path>` exists, and at least 1 of the matches is equal to the given `<value>`36- `//@ !has <path> <value>`: Checks `<path>` exists, but none of the matches equal the given `<value>`.37- `//@ is <path> <value>`: Check `<path>` matches exactly one value, and it's equal to the given `<value>`.38- `//@ is <path> <value> <value>...`: Check that `<path>` matches to exactly every given `<value>`.39   Ordering doesn't matter here.40- `//@ !is <path> <value>`: Check `<path>` matches exactly one value, and that value is not equal to the given `<value>`.41- `//@ count <path> <number>`: Check that `<path>` matches to `<number>` of values.42- `//@ set <name> = <path>`: Check that `<path>` matches exactly one value, and store that value to the variable called `<name>`.4344These are defined in [`directive.rs`].4546### Values4748Values can be either JSON values, or variables.4950- JSON values are JSON literals, e.g. `true`, `"string"`, `{"key": "value"}`.51  These often need to be quoted using `'`, to be processed as 1 value.52  See [§Argument splitting](#argument-splitting)53- Variables can be used to store the value in one path, and use it in later queries.54  They are set with the `//@ set <name> = <path>` directive, and accessed with `$<name>`5556  ```rust57  //@ set foo = $some.path58  //@ is $.some.other.path $foo59  ```6061### Argument splitting6263Arguments to directives are split using the [shlex] crate, which implements POSIX shell escaping.64This is because both `<path>` and `<value>` arguments to [directives](#directives) frequently have both65whitespace and quote marks.6667To use the `@ is` with a `<path>` of `$.index[?(@.docs == "foo")].some.field` and a value of `"bar"` [^why_quote], you'd write:6869```rust70//@ is '$.is[?(@.docs == "foo")].some.field' '"bar"'71```7273[^why_quote]: The value needs to be `"bar"` *after* shlex splitting, because we74    it needs to be a JSON string value.7576[json output]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#json-output77[jsondocck]: https://github.com/rust-lang/rust/tree/HEAD/src/tools/jsondocck78[jsondoclint]: https://github.com/rust-lang/rust/tree/HEAD/src/tools/jsondoclint79[aux-build]: ../tests/compiletest.md#building-auxiliary-crates80[`Id`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/struct.Id.html81[document private items]: https://doc.rust-lang.org/nightly/rustdoc/command-line-arguments.html#--document-private-items-show-items-that-are-not-public82[`directive.rs`]: https://github.com/rust-lang/rust/blob/HEAD/src/tools/jsondocck/src/directive.rs83[shlex]: https://docs.rs/shlex/1.3.0/shlex/index.html84[JSONPath]: https://www.rfc-editor.org/rfc/rfc9535.html