PHPUnitManual:15.1

15.1 애자일 문서 작성 (Agile Documentation)

일반적으로, Extreme Programming 과 같은 애자일 프로세스를 채용한 프로젝트에서는, 문서의 내용이 실제 설계와 코드를 반영하지 못 하는 경우가 많습니다. Extreme Programming 에서는 코드의 공동 소유 (collective code ownership) 가 요구되고, 모든 개발자가 시스템 전체의 동작을 파악할 필요가 있습니다. 작성할 테스트에 대해, 해당 클래스가 무엇을 하는 클래스인지를 한 눈에 알 수 있는 "명확한" 클래스명을 붙인다면, PHPUnit 의 TestDox 기능을 사용하여 자동적으로 문서를 생성할 수 있습니다. 이 문서는 개발자들에게 프로젝트의 각 클래스가 어떻게 동작해야 할지를 파악할 수 있습니다.

PHPUnit 의 TestDox 기능은, 테스트 클래스 내부의 모든 테스트 메소드의 이름을 추출하여 PHP 의 메소드 형식에서 일반 영어 문장 형식으로 변환합니다. 예를 들어, testBalanceIsInitiallyZero() 가 "Balance is initially zero" 로 변환됩니다. 마지막 숫자만 다른 메소드가 존재할 경우 (예: testBalanceCannotBecomeNegative() 와 testBalanceCannotBecomeNegative2()), 문장 "Balance cannot become negative" 는 한 번만 표시되어 모든 테스트가 성공했음을 나타냅니다.

BankAccount 클래스 (from 예12.1 "BankAccount 클래스의 테스트" 를 참조하세요) 의 애자일 문서는 다음과 같습니다.

phpunit --testdox BankAccountTest
PHPUnit 3.7.0 by Sebastian Bergmann.

BankAccount
 [x] Balance is initially zero
 [x] Balance cannot become negative

또한, 애자일 문서를 HTML 이나 PLAIN TEXT 형식으로 작성하여 파일 출력할 수도 있습니다. 이 경우, 인수 --testdox-html 이나 --testdox-text 를 사용합니다.

애자일 문서는, 프로젝트에서 사용하는 외부 패키지에 기대되는 동작을 정리한 문서가 될 수도 있습니다. 외부 패지키는, 해당 패키지가 기대와 다르게 동작할 수도 있다는 리스크를 가집니다. 패키지의 버젼 업에 의해 동작이 변할 수도 있고, 그로 인해 당신의 코드가 오동작할 수도 있습니다. 이러한 일을 방지하기 위해, "이 패키지는 이렇게 동작할 것이다" 라는 것을 test case 로 작성해 둡니다. 테스트가 성공한다면, 기대대로 동작하고 있다는 것을 확인할 수 있습니다. 만약 패키지의 사양을 전부 테스트로 기술할 수 있다면, 외부 패키지가 장래에 버젼 업 되더라도 문제는 발생하지 않을 것입니다. 테스트를 통관했다는 것은, 시스템이 기대대로 동작할 것을 의미하기 때문입니다.