Onionmixer: PHPUnit Appendix B. 선언 Annotations 페이지 추가

2013-07-04T10:11:02Z

PHPUnit Appendix B. 선언 Annotations 페이지 추가

New page

;Appendix B. 선언 Annotations

==선언 Annotations==

선언은 메타 데이터를 나타내는 특별한 구문으로, 프로그래밍 언어의 소스 코드에 추가할 수 있습니다. PHP 자체에는 선언에 관한 전용 문법은 존재하지 않지만, 주석 블럭에 "@선언 인수" 와 같은 태그를 작성하여 선언을 표현하는 표기법이 PHP 커뮤니티에서는 일반적입니다. PHP 에서는 Reflection API 의 getDocComment() 메서드를 사용하여, 함수, 클래스, 메서드, 속성 각각의 주석 블럭에 접근할 수 있습니다. PHPUnit 등의 어플리케이션에서는 이 정보를 토대로 실행 시의 동작을 결정합니다.

이 장에서는 PHPUnit 이 서포트하는 모든 선언에 대해 해설합니다.

===@author===

@author 선언은 @group 선언의 alias 로, 테스트 작성자 별로 필터링할 수 있게 합니다.

===@backupGlobals===

Test case 클래스의 모든 테스트에 대해서, 글로벌 변수의 백업과 복구 기능을 무효화할 수 있습니다. 사용법은 다음과 같습니다.

<syntaxhighlight lang="php">
/**
* @backupGlobals disabled
*/
class MyTest extends PHPUnit_Framework_TestCase
{
// ...
}
</syntaxhighlight>

@backupGlobals 선언은 테스트 메서드 레벨에서 사용할 수도 있습니다. 이를 통해 백업과 복구 작업을 보다 정밀하게 제어할 수 있습니다.

<syntaxhighlight lang="php">
/**
* @backupGlobals disabled
*/
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @backupGlobals enabled
*/
public function testThatInteractsWithGlobalVariables()
{
// ...
}
}
</syntaxhighlight>

===@backupStaticAttributes===

Test case 클래스의 모든 테스트에 대해서, 클래스의 정적 속성의 백업과 복구를 무효화 할 수 있습니다. 사용법은 다음과 같습니다.

<syntaxhighlight lang="php">
/**
* @backupStaticAttributes disabled
*/
class MyTest extends PHPUnit_Framework_TestCase
{
// ...
}
</syntaxhighlight>

The @backupStaticAttributes 선언은 테스트 메서드 레벨에서 사용할 수도 있습니다. 이를 통해 백업과 복구 작업을 보다 정밀하게 제어할 수 있습니다.

<syntaxhighlight lang="php">
/**
* @backupStaticAttributes disabled
*/
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @backupStaticAttributes enabled
*/
public function testThatInteractsWithStaticAttributes()
{
// ...
}
}
</syntaxhighlight>

===@codeCoverageIgnore*===

@codeCoverageIgnore, @codeCoverageIgnoreStart 그리고 @codeCoverageIgnoreEnd 선언을 사용하여, 코드의 특정 행을 coverage 분석 대상에서 제외할 수 있습니다.

사용법은 "Code Blocks의 무시" 를 참조하세요.

===@covers===

@covers 선언을 테스트 코드에서 사용하여, 해당 테스트 메서드가 어떤 메서드를 테스트하는지를 지정할 수 있습니다.

<syntaxhighlight lang="php">
/**
* @covers BankAccount::getBalance
*/
public function testBalanceIsInitiallyZero()
{
$this->assertEquals(0, $this->ba->getBalance());
}
</syntaxhighlight>

@covers 이 지정된 경우, 지정된 메서드에 대해서만 coverage 정보가 얻어집니다.

표B.1 "테스트가 Cover 하는 메서드를 지정하기 위한 선언" 은 @covers 선언의 구문의 리스트입니다.

{| class = "collapsible collapsed" width=100% style = "border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -khtml-border-radius: 10px; -icab-border-radius: 10px; -o-border-radius: 10px; border: 5px groove #000066;"
|- style="color: white; background-color: black;"
|'''Annotation'''||'''설명'''
|- style="vertical-align:top;"
|@covers ClassName::methodName||해당 테스트 메서드가 지정한 메서드를 cover 함을 나타냅니다.
|- style="vertical-align:top;"
|@covers ClassName||해당 테스트 메서드가 지정한 클래스의 모든 메서드를 cover 함을 나타냅니다.
|- style="vertical-align:top;"
|@covers ClassName<extended>||해당 테스트 메서드가 지정한 클래스와 그 부모 클래스 및 인터페이스의 모든 메서드를 cover 함을 나타냅니다.
|- style="vertical-align:top;"
|@covers ClassName::<public>||해당 테스트 메서드가 지정한 클래스의 모든 public 메서드를 cover 함을 나타냅니다.
|- style="vertical-align:top;"
|@covers ClassName::<protected>||해당 테스트 메서드가 지정한 클래스의 모든 protected 메서드를 cover 함을 나타냅니다.
|- style="vertical-align:top;"
|@covers ClassName::<private>||해당 테스트 메서드가 지정한 클래스의 모든 private 메서드를 cover 함을 나타냅니다.
|- style="vertical-align:top;"
|@covers ClassName::<!public>||해당 테스트 메서드가 지정한 클래스의 public 이 아닌 모든 메서드를 cover 함을 나타냅니다.
|- style="vertical-align:top;"
|@covers ClassName::<!protected>||해당 테스트 메서드가 지정한 클래스의 protected 이 아닌 모든 메서드를 cover 함을 나타냅니다.
|- style="vertical-align:top;"
|@covers ClassName::<!private>||해당 테스트 메서드가 지정한 클래스의 private 이 아닌 모든 메서드를 cover 함을 나타냅니다.
|- style="vertical-align:top;"
|@covers ::functionName||해당 테스트 메서드가 지정한 글로벌 함수를 cover 함을 나타냅니다.
|- style="color: black; background-color: gray;"
| colspan="2" |표 B.1. 테스트가 Cover 하는 메서드를 지정하기 위한 선언
|}

===@coversNothing===

@coversNothing 선언을 테스트 코드에서 사용하여, 해당 test case 에 대해서 code coverage 정보를 기록하지 않도록 설정합니다.

이 기능은 통합 테스트 (integration testing) 를 위해 사용할 수 있습니다. 예14.3 "어떤 메서드도 cover 하지 않도록 지정한 테스트" 를 참조하세요.

이 메서드는 클래스 레벨이나 메서드 레벨에서 사용할 수 있고, 모든 @covers 태그를 무시합니다.

===@dataProvider===

테스트 메서드에 임의의 인수를 넘길 수 있습니다. 인수는, 데이터 프로바이더 메서드 ( 예4.4 "배열의 배열을 넘기는 데이터 프로바이더의 사용" 의 provider()) 이 넘깁니다. 사용하는 데이터 프로바이더 메서드를 지정하기 위해서는, @dataProvider 선언을 사용합니다.

"Data Providers" 를 참조하세요.

===@depends===

PHPUnit 에서는 테스트 메서드 간의 의존성을 명시적으로 선언할 수 있습니다.여기서 말하는 의존성이란, 테스트 메서드가 실행되는 순서를 정의하는 것이 아닙니다. 생산자가 테스트 fixture 를 생성하여, fixture 의 인스턴스를 반환하고, 의존하는 소비자가 인스턴스를 받아 이용하는 것을 말합니다. 예4.2 "@depends 선언을 사용한 의존성 표현" 은 @depends 선언을 사용하여 테스트 메서드의 의존성을 표현하는 예입니다.

"테스트 의존성 (Test Dependencies)" 을 참고하세요.

===@expectedException===

예4.7 "@expectedException 선언의 사용법" 은 테스트하는 코드 내부에서 예외가 throw 되었는지 여부를 @expectedException 선언을 사용하여 조사하는 방법입니다.

"예외의 테스트 (Testing Exceptions)" 를 참고하세요.

===@expectedExceptionCode===

@expectedExceptionCode 선언을 @expectedException 과 조합하여 사용하면, throw 된 예외의 에러 코드에 대한 검증이 가능해집니다. 이를 통해 예외를 보다 좁은 범위로 좁힐 수 있습니다.

<syntaxhighlight lang="php">
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @expectedException MyException
* @expectedExceptionCode 20
*/
public function testExceptionHasErrorcode20()
{
throw new MyException('Some Message', 20);
}
}
</syntaxhighlight>

테스트의 실행을 쉽게 하고 중복을 줄이기 위해, 바로가기를 사용하여 클래스 정수를 지정할 수 있습니다. @expectedExceptionCode 에서 "@expectedExceptionCode ClassName::CONST" 구문을 사용합니다.

<syntaxhighlight lang="php">
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @expectedException MyException
* @expectedExceptionCode MyClass::ERRORCODE
*/
public function testExceptionHasErrorcode20()
{
throw new MyException('Some Message', 20);
}
}
class MyClass
{
const ERRORCODE = 20;
}
</syntaxhighlight>

===@expectedExceptionMessage===

@expectedExceptionMessage 선언은 @expectedExceptionCode 와 비슷하게 예외의 에러 메세지에 관해 검증합니다.

<syntaxhighlight lang="php">
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @expectedException MyException
* @expectedExceptionMessage Some Message
*/
public function testExceptionHasRightMessage()
{
throw new MyException('Some Message', 20);
}
}
</syntaxhighlight>

기대되는 메세지를 예외 메세지의 일부로 삼을 수도 있습니다. 이 기능은 특정 이름이나 인수가 예외에 표시되는지를 확인하고자 하면서도 예외 메세지 전체가 고정되지는 않은 경우에 편리합니다.

<syntaxhighlight lang="php">
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @expectedException MyException
* @expectedExceptionMessage broken
*/
public function testExceptionHasRightMessage()
{
$param = "broken";
throw new MyException('Invalid parameter "'.$param.'".', 20);
}
}
</syntaxhighlight>

테스트의 실행을 쉽게 하고 중복을 줄이기 위해, 바로가기를 사용하여 클래스 정수를 지정할 수 있습니다. @expectedExceptionMessage 에서 "@expectedExceptionMessage ClassName::CONST" 구문을 사용합니다. 샘플 코드는 the section called “@expectedExceptionCode” 를 참고하세요.

===@group===

한 테스트를 하나 혹은 복수의 group 에 포함시킬 수 있습니다. @group 선언은 다음과 같이 사용합니다.

<syntaxhighlight lang="php">
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @group specification
*/
public function testSomething()
{
}

/**
* @group regresssion
* @group bug2204
*/
public function testSomethingElse()
{
}
}
</syntaxhighlight>

특정 group 에 포함된 테스트만을 골라서 실행하려는 경우, command-line test runner 에서는 --group 이나 --exclude-group 스위치를 사용합니다. XML 설정 파일에서는, 각각 대응 디렉토리를 설정합니다.

===@outputBuffering===

@outputBuffering 선언을 사용하여 PHP 의 output buffering 을 다음과 같이 제어할 수 있습니다.

<syntaxhighlight lang="php">
/**
* @outputBuffering enabled
*/
class MyTest extends PHPUnit_Framework_TestCase
{
// ...
}
</syntaxhighlight>

@outputBuffering 선언은 테스트 메서드 레벨에서 사용할 수도 있습니다. 이 기능을 통해 output buffering 을 보다 정밀하게 제어할 수 있습니다.

<syntaxhighlight lang="php">
/**
* @outputBuffering disabled
*/
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @outputBuffering enabled
*/
public function testThatPrintsSomething()
{
// ...
}
}
</syntaxhighlight>

===@preserveGlobalState===

테스트를 별도 프로세스에서 실행할 때, PHPUnit 은 부모 프로세스의 글로벌 상태 (state) 를 보존하려 합니다. 부모 프로세스의 모든 글로벌 상태를 serialize 하여, 자식 프로세스에서 unserialize 합니다. 부모 프로세스에 serialize 불가능한 상태가 있을 경우 문제가 발생합니다. 이 문제에 대응하기 위해, 글로벌 상태의 보존을 무효화할 수 있습니다. 이를 위해 @preserveGlobalState 선언을 사용합니다.

<syntaxhighlight lang="php">
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @runInSeparateProcess
* @preserveGlobalState disabled
*/
public function testInSeparateProcess()
{
// ...
}
}
</syntaxhighlight>

===@requires===

@requires 선언을 사용하여 공통된 사전 조건 (예:PHP버젼이나 확장 모듈의 인스톨 상황) 을 만족시키지 않는 경우, 테스트를 패스합니다.

조건으로 지정할 수 있는 내용과 예는 표9.3 "@requires 의 사용예" 를 참고하세요.

===@runTestsInSeparateProcesses===

테스트 클래스의 모든 test case 를, 개별 PHP 프로세스로 실행하도록 지시합니다.

<syntaxhighlight lang="php">
/**
* @runTestsInSeparateProcesses
*/
class MyTest extends PHPUnit_Framework_TestCase
{
// ...
}
</syntaxhighlight>

"'''주의사항''': 기본 설정으로, PHPUnit 은 부모 프로세스의 글로벌 상태를 보존하려 합니다. 부모 프로세스의 모든 글로벌 상태를 serialize 하여, 자식 프로세스에서 unserialize 합니다. 부모 프로세스에 serialize 불가능한 상태가 있을 경우 문제가 발생합니다. 이 문제에 대응하기 위해, 글로벌 상태의 보존을 무효화할 수 있습니다. “@preserveGlobalState” 를 참조하세요.

===@runInSeparateProcess===

해당 테스트를 개별 PHP 프로세스로 실행하도록 지시합니다.

<syntaxhighlight lang="php">
class MyTest extends PHPUnit_Framework_TestCase
{
/**
* @runInSeparateProcess
*/
public function testInSeparateProcess()
{
// ...
}
}
</syntaxhighlight>

:'''주의사항''': 기본 설정으로, PHPUnit 은 부모 프로세스의 글로벌 상태를 보존하려 합니다. 부모 프로세스의 모든 글로벌 상태를 serialize 하여, 자식 프로세스에서 unserialize 합니다. 부모 프로세스에 serialize 불가능한 상태가 있을 경우 문제가 발생합니다. 이 문제에 대응하기 위해, 글로벌 상태의 보존을 무효화할 수 있습니다. “@preserveGlobalState” 를 참조하세요.

===@test===

테스트 메서드의 이름 앞에 test 를 추가하는 대신에, 메서드의 주석 블록에서 @test 선언을 사용하여 해당 메서드가 테스트 메서드임을 지정할 수 있습니다.

<syntaxhighlight lang="php">
/**
* @test
*/
public function initialBalanceShouldBe0()
{
$this->assertEquals(0, $this->ba->getBalance());
}
</syntaxhighlight>

===@testdox===

내용없음

===@ticket===

내용없음

==Notes==
<references />

[[Category:PHPUnitManual]]

PHPUnitManual:B - Revision history

Onionmixer: PHPUnit Appendix B. 선언 Annotations 페이지 추가