From 7fef889f685e95234dfa9da693832c98a6390fae Mon Sep 17 00:00:00 2001
From: Jaime Perez Crespo <jaime.perez@uninett.no>
Date: Fri, 10 Jun 2016 15:29:31 +0200
Subject: [PATCH] Be a bit more verbose with the testing instructions.
---
TESTING.md | 67 ++++++++++++++++++++++++++++++++++++++----------------
1 file changed, 48 insertions(+), 19 deletions(-)
diff --git a/TESTING.md b/TESTING.md
index 2916ae91a..90e6c9d17 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -1,35 +1,64 @@
Testing
=======
-All tests should be in "tests/". The directory structure there replicates the
-main structure of the code. Each class Whatever is tested by a class named
-WhateverTest.php, following the same path as the original.
+Testing your code is crucial to have a stable and good quality product.
+We are therefore slowly increasing the amount of tests we perform, and
+as a rule of thumb **all new code should have associated tests**. If you
+want to contribute to the project with a pull request, make sure to
+**include tests covering your code**. We won't accept pull requests
+without tests or getting the code coverage down, except in very specific
+situations.
-The test classes (WhateverTest) need to extend PHPUnit_Framework_TestCase, and
-inside you can implement how many methods you want. phpunit will only run the
-ones prefixed with "test".
+All the tests reside in the `tests` directory. The directory structure
+there replicates the main structure of the code. Each class is tested by
+a class named with the same name and `Test` appended, having the same
+directory structure as the original, but inside the `tests` directory.
+We also use namespaces, with `SimpleSAML\Test` as the root for standard
+classes, and `SimpleSAML\Test\Module\modulename` for classes located in
+modules.
-You'd usually use the $this->assertSomething() methods provided by
-PHPUnit_Framework_TestCase, but you can also tell phpunit to expect an
-exception to be thrown using phpdoc:
+For example, if you want to test the `SimpleSAML\Utils\HTTP` class
+located in `lib/SimpleSAML/Utils/HTTP.php`, the tests must be in a class
+named `HTTPTest` implemented in
+`tests/lib/SimpleSAML/Utils/HTTPTest.php`, with the following namespace
+definition:
+```php
+namespace SimpleSAML\Test\Utils;
```
-/**
+
+The test classes need to extend `PHPUnit_Framework_TestCase`, and inside
+you can implement as many methods as you want. `phpunit` will only run
+the ones prefixed with "test".
+
+You will usually make use of the `assert*()` methods provided by
+`PHPUnit_Framework_TestCase`, but you can also tell `phpunit` to expect
+an exception to be thrown using *phpdoc*. For example, if you want to
+ensure that the `SimpleSAML\Utils\HTTP::addURLParameters()` method
+throws an exception in a specific situation:
+
+```php
+ /**
* Test SimpleSAML\Utils\HTTP::addURLParameters().
*
* @expectedException \InvalidArgumentException
-*/
+ */
+ public function testAddURLParametersInvalidParameters() {
```
-Run the tests locally by hiding the config-directory in the root (as the tests cannot use that) and running:
+Refer to [the `phpunit` documentation](https://phpunit.de/documentation.html)
+for more information on how to write tests.
-```
+Once you have implemented your tests, you can run them locally. First,
+make sure the `config` directory is **not** in the root of your
+SimpleSAMLphp installation, as the tests cannot use that. Make sure
+you have `phpunit` installed and run:
+
+```sh
phpunit -c tools/phpunit/phpunit.xml
```
-After you've pushed a change, Travis-CI will run your test in the CI platform.
-
-Todo
-----
-
-The tests should use namespaces.
+All the tests are run by our *continuous integration* platform,
+[travis](https://travis-ci.org/simplesamlphp/simplesamlphp). If you are
+submitting a pull request, Travis will run your tests and notify whether
+your code builds or not according to them.
--
GitLab