diff options
| -rw-r--r-- | README.markdown | 1 | ||||
| -rw-r--r-- | docs/tests.markdown | 180 |
2 files changed, 181 insertions, 0 deletions
diff --git a/README.markdown b/README.markdown index 4ce1a26d..e175f660 100644 --- a/README.markdown +++ b/README.markdown @@ -91,6 +91,7 @@ Documentation - [Translations](docs/translations.markdown) - [Coding standards](docs/coding-standards.markdown) +- [Running tests](docs/tests.markdown) The documentation is written in [Markdown](http://en.wikipedia.org/wiki/Markdown). If you want to improve the documentation, just send a pull-request. diff --git a/docs/tests.markdown b/docs/tests.markdown new file mode 100644 index 00000000..0a80aae6 --- /dev/null +++ b/docs/tests.markdown @@ -0,0 +1,180 @@ +How to run units and functionals tests? +======================================= + +[PHPUnit](https://phpunit.de/) is used to run automatic tests on Kanboard. + +You can run tests across different databases (Sqlite, Mysql and Postgresql) to be sure that the result is the same everywhere. + +Requirements +------------ + +- Linux/Unix machine +- PHP command line +- PHPUnit installed +- Mysql and Postgresql (optional) + +Install the latest version of PHPUnit +------------------------------------- + +Simply download the PHPUnit PHAR et copy the file somewhere in your `$PATH`: + +```bash +wget https://phar.phpunit.de/phpunit.phar +chmod +x phpunit.phar +sudo mv phpunit.phar /usr/local/bin/phpunit +phpunit --version +PHPUnit 4.2.6 by Sebastian Bergmann. +``` + +Running unit tests +------------------ + +### Testing with Sqlite + +Sqlite tests use a in-memory database, nothing is written on the filesystem. + +The config file is `tests/units.sqlite.xml`. +From your Kanboard directory, run the command `phpunit -c tests/units.sqlite.xml`. + +Example: + +```bash +phpunit -c tests/units.sqlite.xml + +PHPUnit 4.2.6 by Sebastian Bergmann. + +Configuration read from /Volumes/Devel/apps/kanboard/tests/units.sqlite.xml + +................................................................. 65 / 74 ( 87%) +......... + +Time: 9.05 seconds, Memory: 17.75Mb + +OK (74 tests, 6145 assertions) +``` + +### Testing with Mysql + +You must have Mysql or MariaDb installed on localhost. + +By default, those credentials are used: + +- Hostname: **localhost** +- Username: **root** +- Password: nothing (blank) +- Database: **kanboard_unit_test** + +For each execution the database is dropped and created again. + +The config file is `tests/units.mysql.xml`. +From your Kanboard directory, run the command `phpunit -c tests/units.mysql.xml`. + +Example: + +```bash +phpunit -c tests/units.mysql.xml + +PHPUnit 4.2.6 by Sebastian Bergmann. + +Configuration read from /Volumes/Devel/apps/kanboard/tests/units.mysql.xml + +................................................................. 65 / 74 ( 87%) +......... + +Time: 49.77 seconds, Memory: 17.50Mb + +OK (74 tests, 6145 assertions) +``` + +### Testing with Postgresql + +You must have Postgresql installed on localhost. + +By default, those credentials are used: + +- Hostname: **localhost** +- Username: **postgres** +- Password: **postgres** +- Database: **kanboard_unit_test** + +Be sure to allow the user `postgres` to create and drop databases. +For each execution the database is dropped and created again. + +The config file is `tests/units.postgres.xml`. +From your Kanboard directory, run the command `phpunit -c tests/units.postgres.xml`. + +Example: + +```bash +phpunit -c tests/units.postgres.xml + +PHPUnit 4.2.6 by Sebastian Bergmann. + +Configuration read from /Volumes/Devel/apps/kanboard/tests/units.postgres.xml + +................................................................. 65 / 74 ( 87%) +......... + +Time: 52.66 seconds, Memory: 17.50Mb + +OK (74 tests, 6145 assertions) +``` + +Running functionals tests +------------------------- + +Actually only the API calls are tested. + +Real HTTP calls are made with those tests. +So a local instance of Kanboard is necessary and must listen on `http://localhost:8000`. + +Don't forget that all data will be removed/altered by the testsuite. +Moreover the script will reset and set a new API key. + +1. Start a local instance of Kanboard `php -S 127.0.0.1:8000` +2. Run the testsuite from another terminal + +The same method as above is used to run tests across different databases: + +- Sqlite: `phpunit -c tests/functionals.sqlite.xml` +- Mysql: `phpunit -c tests/functionals.mysql.xml` +- Postgresql: `phpunit -c tests/functionals.postgres.xml` + +Example: + +```bash +phpunit -c tests/functionals.sqlite.xml + +PHPUnit 4.2.6 by Sebastian Bergmann. + +Configuration read from /Volumes/Devel/apps/kanboard/tests/functionals.sqlite.xml + +.......................................... + +Time: 1.72 seconds, Memory: 4.25Mb + +OK (42 tests, 160 assertions) +``` + +Continuous Integration with Travis +---------------------------------- + +After each commit pushed on the main repository, unit tests are executed across 4 different major versions of PHP. + +The Travis config file `.travis.yml` is located on the root directory of Kanboard: + +```yaml +language: php + +php: + - "5.6" + - "5.5" + - "5.4" + - "5.3" + +before_script: wget https://phar.phpunit.de/phpunit.phar +script: php phpunit.phar -c tests/units.sqlite.xml +``` + +As you can see, tests are executed with PHP 5.3, 5.4, 5.5 and 5.6. +However, only Sqlite unit tests are executed on Travis. |