`rustdoc-json` 테스트 스위트

이 페이지는 rustdoc의 json 출력을 테스트하는 rustdoc-json이라는 테스트 스위트만을 다룹니다. rustdoc 테스트에 사용되는 다른 테스트 스위트에 대해서는 §Rustdoc 테스트 스위트를 참조하십시오.

테스트는 compiletest로 실행되며, 일반적인 지시문을 모두 사용할 수 있습니다. 여기에서 자주 사용되는 지시문은 다음과 같습니다.

각 크레이트의 json 출력은 jsondoclint와 jsondocck라는 2개의 프로그램으로 검사됩니다.

jsondoclint

jsondoclint는 모든 Id가 index(또는 paths)에 존재하는지 검사합니다. 이를 통해 댕글링(dangling) Id가 없음을 보장합니다.

jsondocck는 주석에 주어진 지시문을 처리하여 출력의 값이 예상한 대로인지 단언합니다. 그런 점에서 htmldocck와 매우 비슷합니다.

쿼리 언어로 JSONPath를 사용하는데, 이는 경로를 받아 그 경로와 일치한다고 하는 값들의 목록을 반환합니다.

//@ has <path>: <path>가 존재하는지, 즉 최소 1개의 값과 일치하는지 검사합니다.
//@ !has <path>: <path>가 존재하지 않는지, 즉 0개의 값과 일치하는지 검사합니다.
//@ has <path> <value>: <path>가 존재하고, 일치하는 값 중 최소 1개가 주어진 <value>와 같은지 검사합니다.
//@ !has <path> <value>: <path>가 존재하지만, 일치하는 값 중 어느 것도 주어진 <value>와 같지 않은지 검사합니다.
//@ is <path> <value>: <path>가 정확히 하나의 값과 일치하고, 그 값이 주어진 <value>와 같은지 검사합니다.
//@ is <path> <value> <value>...: <path>가 주어진 모든 <value>와 정확히 일치하는지 검사합니다. 여기서 순서는 중요하지 않습니다.
//@ !is <path> <value>: <path>가 정확히 하나의 값과 일치하고, 그 값이 주어진 <value>와 같지 않은지 검사합니다.
//@ count <path> <number>: <path>가 <number>개의 값과 일치하는지 검사합니다.
//@ set <name> = <path>: <path>가 정확히 하나의 값과 일치하는지 검사하고, 그 값을 <name>이라는 변수에 저장합니다.

이들은 directive.rs에 정의되어 있습니다.

값은 JSON 값이거나 변수일 수 있습니다.

JSON 값은 JSON 리터럴입니다. 예를 들면 true, "string", {"key": "value"} 등이 있습니다. 이러한 값이 하나의 값으로 처리되려면 '로 감싸야 하는 경우가 많습니다. §인자 분할을 참조하십시오.
변수를 사용하면 한 경로의 값을 저장해 두었다가 이후 쿼리에서 사용할 수 있습니다. 변수는 //@ set <name> = <path> 지시문으로 설정하며, $<name>으로 접근합니다.
```
#![allow(unused)]
fn main() {
//@ set foo = $some.path
//@ is $.some.other.path $foo
}
```

지시문의 인자는 POSIX 셸 이스케이프를 구현하는 shlex 크레이트를 사용하여 분할됩니다. 이는 지시문에 전달되는 <path> 인자와 <value> 인자 모두에 공백과 따옴표가 함께 들어 있는 경우가 많기 때문입니다.

$.index[?(@.docs == "foo")].some.field라는 <path>와 "bar"라는 값¹으로 @ is를 사용하려면 다음과 같이 작성합니다.

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