`rustdoc-json` テストスイート

このページでは、rustdoc の json output をテストする、rustdoc-json という名前のテストスイートについて特に説明します。 rustdoc のテストに使用される他のテストスイートについては、§Rustdoc テストスイートを参照してください。

テストは compiletest で実行され、通常の一連のディレクティブを利用できます。ここで頻繁に使用されるディレクティブは次のとおりです。

各クレートの JSON 出力は、jsondoclint と jsondocck という 2 つのプログラムでチェックされます。

jsondoclint

jsondoclint は、すべての Id が index（または paths）に存在することをチェックします。これにより、ダングリングな Id が存在しないことを確認します。

jsondocck は、出力内の値が期待どおりであることをアサートするために、コメント内で指定されたディレクティブを処理します。その点では htmldocck とよく似ています。

これはクエリ言語として JSONPath を使用します。JSONPath はパスを受け取り、そのパスがマッチするとされる値のリストを返します。

//@ has <path>: <path> が存在すること、つまり少なくとも 1 つの値にマッチすることをチェックします。
//@ !has <path>: <path> が存在しないこと、つまり 0 個の値にマッチすることをチェックします。
//@ has <path> <value>: <path> が存在し、マッチしたもののうち少なくとも 1 つが指定された <value> と等しいことをチェックします。
//@ !has <path> <value>: <path> が存在するが、マッチしたもののいずれも指定された <value> と等しくないことをチェックします。
//@ is <path> <value>: <path> がちょうど 1 つの値にマッチし、それが指定された <value> と等しいことをチェックします。
//@ is <path> <value> <value>...: <path> が指定されたすべての <value> にちょうどマッチすることをチェックします。ここでは順序は関係ありません。
//@ !is <path> <value>: <path> がちょうど 1 つの値にマッチし、その値が指定された <value> と等しくないことをチェックします。
//@ count <path> <number>: <path> が <number> 個の値にマッチすることをチェックします。
//@ set <name> = <path>: <path> がちょうど 1 つの値にマッチすることをチェックし、その値を <name> という名前の変数に保存します。

これらは directive.rs で定義されています。

値には JSON 値または変数を指定できます。

JSON 値は JSON リテラルです。例: true、"string"、{"key": "value"}。これらは 1 つの値として処理されるように、多くの場合 ' で引用する必要があります。 §引数の分割を参照してください。
変数は、あるパス内の値を保存し、後続のクエリで使用するために利用できます。変数は //@ set <name> = <path> ディレクティブで設定し、$<name> でアクセスします。
```
#![allow(unused)]
fn main() {
//@ set foo = $some.path
//@ is $.some.other.path $foo
}
```

ディレクティブへの引数は、POSIX シェルのエスケープを実装する shlex クレートを使用して分割されます。これは、ディレクティブへの <path> 引数と <value> 引数のどちらにも、空白と引用符の両方が頻繁に含まれるためです。

<path> に $.index[?(@.docs == "foo")].some.field、値に "bar" ¹ を指定して @ is を使用するには、次のように書きます。

#![allow(unused)]
fn main() {
//@ is '$.is[?(@.docs == "foo")].some.field' '"bar"'
}