thekid/rfc — Issue #40: RFC 0032: Add annotations for Unittest API
Author: thekid
Created: 2011-10-09 14:18:11+00:00
State: open

Scope of Change
====
The unittest API should be extended to support some of the annotation
based features that will be introduces with JUnit 4.0.

These annotations include
. @expect
. @timeout

Rationale
====
Sometimes one might not want to check for certain return values. Issueing
exceptions to check error handling code is even quite common.
The annotation `@expect` will simplify the common case where one needs to
check that a specific exception has been thrown.

The annotation @timeout can be used to check the runtime behaviour of
a method.

Functionality
====
The @expect annotation takes the name of the expected exception:

```php
throwExpectedException();
}
?>
```

The @timeout annotation takes the amount of seconds a method may take
to execute.

```php

```

The method will be interrupted if it didn't complete within the time
specified and the result will be assumed as failed.

Security considerations
====
n/a

Speed impact
====
Of course, exception handling is a slow thing, but this doesn't count
for unit testing.

Dependencies
====
- ext/pcntl for the timeout thing
http://php3.de/pcntl_alarm

Related documents
====
- JUnit 4 overview
http://www.beust.com/weblog/archives/000292.html

- JUnit 4.0 (german)
http://www.frankwestphal.de/JUnit4.0.html

- Patch against util.profiling.unittest.TestCase
http://xp-framework.net/downloads/rfc0032.diff

- XP Unit testing introduction
http://xp-framework.info/xml/xp.en_US/news/view?67

Comments
====
- testing timeouts seems a bit vague - runtime behavior may be affected by
a whole lot of things. Maybe we have no application for this, then.
kiesel, Wed Jul 20 00:51:35 CEST 2005

- the resolution of pcntl_alarm is seconds - this may be too much for
fine-grained checks. If one can live without the method being interrupted
but only profiled for its execution time, the resolution can be increased.
Then, again, the question is if there aren't too many external influences
for this.
JUnit 4's @timeout annotation specifies the timeout in milliseconds.
kiesel, Wed Jul 20 00:53:19 CEST 2005

- the attached patch implements the @expect attribute; it does not implement
the timeout as I personally think that it is not of use enough. Someone
may come up with another patch or convince me:)
The @expect attribute has also been changed to take the fully qualified
classname of the exception class.
kiesel, Sun Aug 21 12:17:27 CEST 2005

- The @expect annotation was implemented. If @timeout makes sense (and
because it doesn't work under Windows) we can implement it later.
friebe, Thu Sep 1 10:40:45 CEST 2005