문서 코드 예제를 테스트해야 하는 이유

소개

저는 위키 소프트웨어를 사용하여 내부 문서를 호스팅하는 회사에서 근무했습니다. 설명서에는 설정, 사용 방법, 온보딩 및 아키텍처 페이지가 포함되어 있습니다. 페이지가 시대에 뒤떨어지기 때문에 신체 상해는 몇 년 후에 뒤따를 것입니다. 최신 정보를 찾고 싶을 때 어떤 위키를 사용해야 할지 막막했습니다.

어느 날 제대로 실행되지 않는 코드 예제를 사용하려고 했습니다. 한 시간 동안 디버깅한 후 코드 예제가 깨졌다는 것을 알았습니다. 슬랙에 글을 올리기 전까지는 몰랐는데 누군가 답장을 하더군요. 그리고 한 달 후 다른 사람이 똑같은 문제를 게시하는 것을 보았습니다. 죄송합니다. 문제를 해결하게 되어 너무 기뻤고 결국 Wiki를 업데이트하지 않았습니다.

코드로서의 문서 사례

개발자 문서로서의 위키의 주요 문제는 위키가 진실의 근원인 실제 코드에서 멀리 떨어져 있다는 것입니다. 코드를 참조해야 하는 경우 항상 코드와 함께 문서를 작성하는 것을 지지합니다. 문서는 일반적으로 Markdown 파일로 코드와 동일한 버전 제어 도구 내에 존재하기 때문에 "docs-as-code"라고 합니다. 코드와 문서 간에 강력한 링크를 만들 수 있습니다. 이를 통해 문서는 코드베이스에서 종속성을 가져오거나 코드베이스에 나타나는 그대로 코드를 표시할 수 있습니다.

코드 예제를 가져오고 테스트하는 방법

Docploy를 사용하면 docploy/docs 폴더에 Markdown 파일을 작성하고, docploy/snippets 폴더에 코드 예제를 추가하고, snippet 태그를 사용하여 Markdown 파일에서 해당 코드 예제를 직접 렌더링할 수 있습니다. 다음은 스니펫 태그를 사용하는 방법의 예입니다.



코드 스니펫은 다음과 같습니다.



Markdown 파일에 코드를 직접 포함하지 않고 별도의 파일에서 코드를 가져오기로 결정했습니다. 파일이 코드가 포함된 실제 파일처럼 취급될 수 있기 때문에 코드베이스별 린터, 구문 강조 표시 및 테스트를 사용할 수 있기 때문입니다. 코드가 있는 실제 파일입니다.

가져온 코드를 테스트할 수 있는 문을 열어주기 때문에 마지막 항목인 테스트 조각에 초점을 맞출 것입니다.

위에서 가져온 파일의 내용은 다음과 같습니다.

describe('example', () => {
  it('should return 2', () => {
    // [start]
    function sum() {
      return 1 + 1;
    }
    // [end]
    expect(sum()).toEqual(2);
  });
});

파일의 하위 집합만 렌더링되었음을 알 수 있습니다. 우리는 실제로 Jest 단위 테스트를 가져오고 있으며 // [start]와 // [end] 주석 블록 사이의 코드만 렌더링하고 있습니다. 이것은 모두 의도적입니다. 이를 통해 문서를 배포하기 전에 코드 예제에서 어설션을 테스트할 수 있습니다. 이렇게 하면 오래된 코드 예제 문제가 해결됩니다. 인터페이스가 중단된 테스트 파일에서 종속성을 가져오면 CI 빌드가 실패하고 문서를 배포할 수 없습니다.

Docploy는 가져온 파일을 CI 파이프라인의 일부로 일반 단위 테스트인 것처럼 실행합니다. 이것이 Docploy가 CI 파이프라인에 긴밀하게 통합되는 이유입니다.

결론

문서 코드 예제를 테스트하는 것이 과잉처럼 보일 수 있지만 문서 페이지 수가 증가함에 따라 자신과 사용자의 시간을 많이 절약할 수 있습니다. 모든 코드 예제를 수동으로 실행하기 위해 정기적으로 설명서를 검토할 필요가 없기 때문에 유지 관리 시간을 절약할 수 있습니다. 설명서의 사용자는 코드 예제가 실행되고 중단된 코드 예제를 디버깅하는 데 시간을 낭비하지 않는다는 것을 확신할 수 있습니다.

코드를 프로덕션에 배포하고 모든 것이 잘되기를 바라시겠습니까? 몇 주마다 다른 제품 흐름을 수동으로 테스트하시겠습니까? 지금은 괜찮을 수 있지만 여러 기여자와 많은 사용자가 있는 경우 문서에서 테스트를 실행하는 자동화된 방법이 필요합니다. 이러한 문제를 방지하려면 최신 소프트웨어 엔지니어링 원칙을 문서에 적용해야 합니다.