| 1 | title: Testing a Photon Component, Application or Project␊ |
| 2 | description:␊ |
| 3 | Automated testing improves the software quality by preventing regressions␊ |
| 4 | in the code. After and while implementing new features, you create and run␊ |
| 5 | the software unit tests to ensure that you do not break anything and that␊ |
| 6 | the software runs as expected. Photon provides an easy way to run your tests.␊ |
| 7 | +++␊ |
| 8 | keywords: tests, unit testing, continuous integration␊ |
| 9 | content:␊ |
| 10 | ␊ |
| 11 | # Introduction␊ |
| 12 | ␊ |
| 13 | Software testing is a very large field but the goal is always the␊ |
| 14 | same, getting a software with the minimum number of bugs and doing␊ |
| 15 | what it is supposed to do.␊ |
| 16 | ␊ |
| 17 | **Photon** provides you with some tools to help you perform some of␊ |
| 18 | the testing of your software, the tools covers:␊ |
| 19 | ␊ |
| 20 | - Unit testing with [PHPUnit][phpunit];␊ |
| 21 | - Code coverage analysis with [PHPUnit][phpunit] and [X-Debug][xdebug];␊ |
| 22 | - Continuous integration (planned);␊ |
| 23 | - Performance analysis.␊ |
| 24 | ␊ |
| 25 | You will need to manage yourself all the end user testing and in␊ |
| 26 | browser testing.␊ |
| 27 | ␊ |
| 28 | # How to Run the Unit Tests␊ |
| 29 | ␊ |
| 30 | The unit tests with **Photon** are conventional [PHPUnit][phpunit]␊ |
| 31 | tests. Go in project folder, where the `config.test.php` is available␊ |
| 32 | and simply run:␊ |
| 33 | ␊ |
| 34 | $ photon runtests␊ |
| 35 | PHPUnit 3.5.5 by Sebastian Bergmann.␊ |
| 36 | ␊ |
| 37 | ..␊ |
| 38 | ␊ |
| 39 | Time: 1 second, Memory: 4.50Mb␊ |
| 40 | ␊ |
| 41 | OK (2 tests, 5 assertions)␊ |
| 42 | ␊ |
| 43 | Writing code coverage data to XML file, this may take a moment.␊ |
| 44 | Code coverage 12/12 (100%)␊ |
| 45 | ␊ |
| 46 | You see here that it automatically find the tests, run them and␊ |
| 47 | perform a code coverage analysis of your code.␊ |
| 48 | ␊ |
| 49 | A couple of options are available if you want to run You ␊ |
| 50 | ␊ |
| 51 | # How to Write the Unit Tests␊ |
| 52 | ␊ |
| 53 | First you need to know a bit [PHPUnit][phpunit], because this is the␊ |
| 54 | framework used to write the tests. The choice of *PHPUnit* was␊ |
| 55 | influenced by the active development and ecosystem around this␊ |
| 56 | framework. Basically, this is the standard unit testing library for␊ |
| 57 | PHP and it had the nice idea to decrease its level of bloat for the␊ |
| 58 | programmers in the last release.␊ |
| 59 | ␊ |
| 60 | The simplest test is a `tests.php` file in your application folder,␊ |
| 61 | for example: `yourproject\apps\helloworld\tests.php`. Just put:␊ |
| 62 | ␊ |
| 63 | <?php␊ |
| 64 | namespace helloworld\tests;␊ |
| 65 | class MySimpleTest extends \PHPUnit_Framework_TestCase␊ |
| 66 | {␊ |
| 67 | /**␊ |
| 68 | * Simply test that foo returns true.␊ |
| 69 | *␊ |
| 70 | * It does not try to retrieve the data afterwards.␊ |
| 71 | */␊ |
| 72 | public function testHelloFoo()␊ |
| 73 | {␊ |
| 74 | $this->assertEquals(true, \helloworld\hello\Base::foo('yeah'));␊ |
| 75 | }␊ |
| 76 | ␊ |
| 77 | /**␊ |
| 78 | * Simple failed test.␊ |
| 79 | */␊ |
| 80 | public function testHelloFailed()␊ |
| 81 | {␊ |
| 82 | $this->assertEquals(true, false);␊ |
| 83 | }␊ |
| 84 | }␊ |
| 85 | ␊ |
| 86 | Then run:␊ |
| 87 | ␊ |
| 88 | $ photon runtests␊ |
| 89 | ␊ |
| 90 | and enjoy the testing. What you need to notice is:␊ |
| 91 | ␊ |
| 92 | - you extend `\PHPUnit_Framework_TestCase` and not␊ |
| 93 | `PHPUnit_Framework_TestCase`. The backslash in front is important as␊ |
| 94 | the class lives in the global namespace.␊ |
| 95 | ␊ |
| 96 | - you can also have more test namespaces, as long as they are sub␊ |
| 97 | namespaces of 'yourapplication\tests` and the files in the␊ |
| 98 | `yourproject/apps/yourapplication/tests/` folder.␊ |
| 99 | ␊ |
| 100 | At the end, you write your tests exactly as you would write them with␊ |
| 101 | [PHPUnit][phpunit]. You can even run *PHPUnit* yourself from the␊ |
| 102 | command line to test your application. This is very important to allow␊ |
| 103 | you to reuse code from other projects into your own **Photon**␊ |
| 104 | projects. That is, **Photon** will not force you to rewrite your tests␊ |
| 105 | just to go well with it. **Photon** is just bootstrapping *PHPUnit*␊ |
| 106 | for you.␊ |
| 107 | ␊ |
| 108 | # Complex Unit Tests␊ |
| 109 | ␊ |
| 110 | In the real world, unit tests need to interact with your database,␊ |
| 111 | other web services and maybe other ØMQ components. This means that you␊ |
| 112 | need to provide your unit tests with some special configuration. You may also want to run some complex operations at the start of the tests.␊ |
| 113 | ␊ |
| 114 | By default, **Photon** uses:␊ |
| 115 | ␊ |
| 116 | - `config.test.php` file in your project folder for your project configuration;␊ |
| 117 | - `photon/testbootstrap.php` to setup the auto loading of the classes and load your configuration.␊ |
| 118 | ␊ |
| 119 | You can use different configuration files, to run your tests with␊ |
| 120 | different setup, by using the `--conf` option, for example:␊ |
| 121 | `--conf=other/config.test.php`. For a small level of security, if the␊ |
| 122 | configuration file is named `config.php` the tests will not run. This␊ |
| 123 | is just to avoid you the bad luck of running your tests with your␊ |
| 124 | production settings by mistake...␊ |
| 125 | ␊ |
| 126 | You can use a different bootstrap file with the␊ |
| 127 | `--bootstrap=path/to/bootstrap.php` option. ␊ |
| 128 | ␊ |
| 129 | # Self Testing of Photon␊ |
| 130 | ␊ |
| 131 | To test your **Photon** installation, you can run the self test procedure:␊ |
| 132 | ␊ |
| 133 | $ photon selftest␊ |
| 134 | ␊ |
| 135 | if you find a bug in **Photon**, please run the self test procedure␊ |
| 136 | and if you can write a test to showcase the bug, then, you are going␊ |
| 137 | to make the developers very happy!␊ |
| 138 | ␊ |
| 139 | [phpunit]: ␊ |
| 140 | [xdebug]: |
