rustdoc-html 테스트 스위트
이 페이지에서는 rustdoc의 HTML 출력을 테스트하는 데 쓰는 rustdoc-html 테스트 스위트를 설명합니다. 다른 rustdoc 전용 테스트 스위트는 Rustdoc 테스트 스위트를 참조하십시오.
이 테스트 스위트의 각 테스트 파일은 단순한 Rust 소스 파일 file.rs이며, 일반 Rust 코드 주석 안에 이른바 지시문이 곳곳에 들어 있습니다. 지시문에는 Compiletest 지시문과 HtmlDocCk 지시문의 두 종류가 있습니다.
전자에 관해 더 알아보려면 Compiletest 지시문을 읽어 보십시오. 후자에 관해서는 이어지는 내용을 읽어 주십시오.
내부적으로 compiletest는 보조 검사 스크립트인 htmldocck.py를 호출합니다.
HtmlDocCk 지시문
HtmlDocCk 지시문은 생성된 HTML에 제약 조건을 거는 단언문입니다. //@ 주석 형태를 취한다는 점에서 compiletest에 전달하는 지시문과 비슷해 보이지만, 결국 둘은 완전히 별개이며 서로 다른 프로그램이 처리합니다.
HTML 문서 트리의 일부를 쿼리할 때는 XPath를 사용합니다.
입문 예제:
//@ has file/type.Alias.html
//@ has - '//*[@class="rust item-decl"]//code' 'type Alias = Option<i32>;'
pub type Alias = Option<i32>;여기서는 크레이트 file에 대해 생성된 문서에 공개 타입 별칭 Alias의 페이지가 있고, 그 페이지 맨 위에 있는 코드 블록에 해당 항목이 예상대로 렌더링되어 있는지 검사합니다. //*[@class="rust item-decl"]//code는 XPath 표현식입니다.
관례상 이러한 지시문은 테스트하려는 대상 바로 위에 둡니다. 그러나 HtmlDocCk는 지시문만 찾기 때문에 엄밀히 말해 반드시 그렇게 둘 필요는 없습니다.
모든 지시문은 PATH 인자를 받습니다. 같은 내용을 반복하지 않으려면 이 인자에 -를 전달하여 이전 PATH 인자를 재사용할 수 있습니다. 경로에 크레이트 이름이 들어가므로, 관례적으로 크레이트 루트에 #![crate_name = "foo"] 속성을 추가하여 최종 경로를 짧게 만듭니다.
COUNT와 PATH의 특수한 - 형태를 제외한 모든 인자는 셸 스타일의 따옴표(작은따옴표 또는 큰따옴표)로 감싼 문자열 형태를 취합니다.
모든 지시문(files 제외)은 이름 앞에 !를 붙여 부정할 수 있습니다. 부정 지시문을 추가하기 전에 주의 사항을 읽어 보십시오.
셸 명령과 마찬가지로, 지시문의 마지막 문자가 \이면 지시문을 여러 줄에 걸쳐 쓸 수 있습니다. 이 경우 다음 줄은 @ 없이 //로 시작해야 합니다.
compiletest 지시문과 마찬가지로 지시문 이름과 인자를 구분할 때 공백 외에 콜론 :을 쓸 수도 있지만, HtmlDocCk 지시문에서는 공백을 권장합니다.
CHANNEL이 현재 릴리스 채널(예: stable 또는 nightly)을 가리키는 URL https://doc.rust-lang.org/CHANNEL을 참조하려면 XPath, PATTERN 인자, 스냅숏 파일에서 특수 문자열 {{channel}}을 사용하십시오.
사용할 수 있는 모든 지시문은 다음과 같습니다:
has
사용법 1:
//@ has PATH
PATH로 지정한 파일이 존재하는지 검사합니다.
사용법 2:
//@ has PATH XPATH PATTERN
PATH로 지정한 공백 정규화된1 파일에서 XPATH로 선택한 각 요소/속성/텍스트의 텍스트가 (마찬가지로 공백 정규화된) 문자열 PATTERN과 일치하는지 검사합니다.
팁: 공백 정규화를 피하고 싶거나 정규식으로 매칭하고 싶다면 대신 matches를 사용하십시오.
hasraw
사용법:
//@ hasraw PATH PATTERN
PATH로 지정한 공백 정규화된1 파일의 내용이 (마찬가지로 공백 정규화된) 문자열 PATTERN과 일치하는지 검사합니다.
팁: 공백 정규화를 피하고 싶거나 정규식으로 매칭하고 싶다면 대신 matchesraw를 사용하십시오.
matches
사용법:
//@ matches PATH XPATH PATTERN
PATH로 지정한 파일에서 XPATH로 선택한 각 요소 / 속성 / 텍스트의 텍스트가 Python 방식2 정규식 PATTERN과 일치하는지 검사합니다.
matchesraw
사용법:
//@ matchesraw PATH PATTERN
PATH로 지정한 파일의 내용이 Python 방식2 정규식 PATTERN과 일치하는지 검사합니다.
count
사용법:
//@ count PATH XPATH COUNT
PATH로 지정한 파일 안에서 XPATH에 대한 일치 항목이 정확히 COUNT개인지 검사합니다.
snapshot
사용법:
//@ snapshot NAME PATH XPATH
PATH로 지정한 파일에서 XPATH로 선택한 요소 / 텍스트가 FILE_STEM.NAME.html 파일에 미리 기록된 서브트리 또는 텍스트(“스냅숏”)와 일치하는지 검사합니다. 여기서 FILE_STEM은 테스트 파일의 파일 스템입니다.
현재 서브트리/텍스트를 기댓값으로 인정하려면 compiletest에 --bless 옵션을 전달하십시오. 이렇게 하면 앞에서 언급한 파일을 덮어씁니다(파일이 없으면 새로 만듭니다). 채널에 따라 달라지는 URL https://doc.rust-lang.org/CHANNEL은 특수 문자열 {{channel}}로 자동 정규화됩니다.
has-dir
사용법:
//@ has-dir PATH
PATH로 지정한 디렉터리가 존재하는지 검사합니다.
files
사용법:
//@ files PATH ENTRIES
PATH로 지정한 디렉터리에 정확히 ENTRIES만 들어 있는지 검사합니다. ENTRIES는 따옴표로 감싼 문자열 안에 적은 Python 방식의 문자열 리스트입니다.
예시: //@ files "foo/bar" '["index.html", "sidebar-items.js"]'
Compiletest 지시문(요약)
소개에서 언급했듯이 compiletest 지시문도 사용할 수 있습니다. 무엇보다도 이 지시문을 사용하면 보조 크레이트를 등록하고, 테스트 대상인 rustdoc 바이너리에 플래그를 전달할 수 있습니다. 아직 지시문에 대해 전혀 모른다면 해당 장을 읽어 보기를 강력히 권장합니다.
다음은 특히 이 테스트 스위트에 해당하는 몇 가지 세부 사항입니다.
rustdoc에 플래그를 전달할 때//@ compile-flags와//@ doc-flags를 모두 사용할 수 있지만, 의도를 드러내려면 후자를 사용하십시오. 전자는rustc를 위한 것입니다.- 보조 크레이트가 있는 테스트 파일에
//@ build-aux-docs를 추가하여 보조 크레이트를rustc로 컴파일할 뿐만 아니라rustdoc로 문서화도 하도록 하십시오.
주의 사항
요소나 텍스트 조각이 없음을 테스트하는 방식은 상당히 취약하며 향후 변경에 잘 대비하지 못합니다.
생성된 HTML 문서 트리의 형태가 이따금 바뀌는 것은 드문 일이 아닙니다. 예를 들어 CSS 클래스 이름이 바뀌는 경우가 여기에 해당합니다.
그런 일이 생기면 긍정 검사는 (XPath 표현식이 충분히 일반적이거나 느슨하다면) 의도한 요소 / 속성 / 텍스트에 계속 일치하여 올바른 대상을 계속 테스트하거나, 그렇지 않으면 실패하여 변경 작성자가 해당 검사를 살펴볼 수밖에 없게 만듭니다.
반면 부정 검사(예: //@ !has PATH XPATH PATTERN)는 XPath 표현식이 “더 이상” 일치하지 않아도 실패하지 않습니다. 따라서 “형태“를 바꾼 작성자는 알림을 받지 못하며, 그 결과 다른 누군가가 생성된 문서에 PATTERN을 의도치 않게 다시 도입하더라도 원래의 부정 검사는 실패하지 않습니다.
참고: 부정 검사는 사용하지 마십시오!
팁: 피할 수 없다면, “형태“를 바꾸는 사람들이 이를 알아차리고 부정 검사를 갱신할 수 있도록 반드시 바로 가까이에 그에 대응하는 긍정 검사를 함께 두십시오!
제한 사항
HtmlDocCk는 Python 표준 라이브러리의 XPath 구현을 사용합니다. 이로 인해 다음과 같은 몇 가지 제한 사항이 있습니다.
- 구현상의 결함 때문에 모든
XPATH인자는//로 시작해야 합니다. - 많은 XPath 기능(함수, 축 등)은 지원되지 않습니다.
- 적격 HTML만 파싱할 수 있습니다(rustdoc이 짝이 맞지 않는 태그를 출력하지 않기를 바랍니다).
또한 compiletest 리비전은 지원되지 않습니다.