From 58a4e6cc75bc6494664c3f42aeeb64b450d2ecc6 Mon Sep 17 00:00:00 2001 From: Filip Klimes Date: Sun, 11 Jan 2015 01:11:31 +0100 Subject: [PATCH] Tester: added new section about running Tester with Travis CI --- cs/@docmenu.texy | 2 +- cs/testing-with-travis.texy | 250 ++++++++++++++++++++++++++++++++++++ en/@docmenu.texy | 2 +- en/testing-with-travis.texy | 246 +++++++++++++++++++++++++++++++++++ 4 files changed, 498 insertions(+), 2 deletions(-) create mode 100644 cs/testing-with-travis.texy create mode 100644 en/testing-with-travis.texy diff --git a/cs/@docmenu.texy b/cs/@docmenu.texy index ad20da716c..d424c9b468 100644 --- a/cs/@docmenu.texy +++ b/cs/@docmenu.texy @@ -20,7 +20,7 @@ - [Zpracování obrázků |images] - [Cache |caching] - [Lokalizace |localization] -- [Testování |testing] +- [Testování |testing], [Průběžná integrace |testing-with-travis] - [Stránkování |pagination] - [Auto-loading tříd |auto-loading] - [Vyhledávání souborů a adresářů |finder] diff --git a/cs/testing-with-travis.texy b/cs/testing-with-travis.texy new file mode 100644 index 0000000000..47b603dd25 --- /dev/null +++ b/cs/testing-with-travis.texy @@ -0,0 +1,250 @@ +Průběžné testování s Nette Tester +******************************** + +/--div .[perex] +Znáte to. Napsali jste testy, které teď procházejí, poplácali se po zádech a váš spánek začal být mnohem klidnější. Máte jistotu, že váš kód spolehlivě funguje. A pak se to stane. Hodiny ukazují 3:15 a do nočního ticha se zakousne nepříjemný zvuk drnčení mobilu na nočním stolku. Volá šéf. Zase to nefunguje. Zalije vás studený pot. Vždyť na to máme testy! V tu chvíli se vynoří vzpomínka na páteční odpoledne - spěcháte domů a zapomínáte spustit testy po poslední úpravě. + +Abyste předešli podobným zážitkům, ukážeme si, jak průběžně testovat pomocí populárního nástroje [Travis CI](https://travis-ci.org/): + +- nastavení testovacího prostředí +- instalace závislostí pomocí Composeru +- spouštění testů pomocí Nette/Tester +- nastavení dalších služeb +- [TL;DR |#Výsledný soubor] +- integrace s GitHubem +\-- + +Jak funguje Travis CI +===================== + +Travis CI((Continuous Integration)) (dále jen Travis) je velmi populární služba pro automatizaci [průběžné integrace](http://cs.wikipedia.org/wiki/Průběžná_integrace). Je poskytována zdarma((Pro soukromé repozitáře je zpoplatněna.)) a nabízí automatizované spouštění testů po zápisu změny do repozitáře. Je plně integrována do prostředí GitHubu. + +Travis se konfiguruje souborem `.travis.yml` umístěným v kořenovém adresáři projektu. Obsahuje několik bloků, které si podrobněji popíšeme. Ani jeden z bloků není povinný. Pokud bychom ovšem vynechali `script`, Travis by se snažil spouštět testy pomocí `phpunit`. + +Bloky jsou spouštěny v pořadí +- `before_install` +- `install` +- `before_script` +- `script` +- `after_success` nebo `after_failure` +- `after_script` + +.[caution] +Soubor `.travis.yml` dovoluje odsazovat pouze mezerami. Syntaktickou správnost si můžete ověřit [pomocí validátoru |http://lint.travis-ci.org/]. + +Pro podrobnější informace si přečtěte [oficiální dokumentaci |http://docs.travis-ci.com]. + +Vytvoření .travis.yml +===================== + +Nastavení jazyka +---------------- + +Nejprve je potřeba pomocí `language` Travis informovat, pro jaký jazyk má prostředí nastavit. Na dalších řádcích uvádíme, pro jaké verze PHP budeme chtít náš projekt otestovat. Neuvedení setinkového čísla znamená použití nejnovější dostupné verze. Testy pak budou spuštěny pro každou verzi zvlášť. Nette Tester podporuje i [HHVM](http://hhvm.com), můžeme ho tedy přidat také. + +/-- +language: php + +php: + - 5.3.3 + - 5.4 + - 5.5 + - 5.6 + - hhvm +\-- + +Proměnné prostředí +------------------ + +V sekci `env` nastavujeme další varianty prostředí pro běh testů. Pro každou odrážku se skripty provedou samostatně a v jedné odrážce lze definovat více proměnných. Dále v textu budeme používat proměnnou `TESTER_PHP_BIN`, abychom pro HHVM mohli testy pouštět s parametrem `-p hhvm`. + +/-- +env: + - TESTER_PHP_BIN="php-cgi" + - TESTER_PHP_BIN="hhvm" +\-- + +Uvedené sekce php a env nám zajistí spuštění testů celkem 10x. Pro pět verzí PHP a dvě varianty proměnných prostředí. + +Instalace závislostí +-------------------- + +.[note] +Návod předpokládá, že závislosti testovaného projektu jsou spravovány pomocí nástroje Composer, a nette/tester je uveden jako závislost pro vývoj. Jak nastavit Composer najdete v kapitole [Composer |composer]. + +V bloku `install` nainstalujeme pomocí Composeru závislosti našeho projektu. Každá odrážka znamená samostatný příkaz. Composer ve výchozím nastavení nainstaluje i dev závislosti. Dobrým zvykem je použít `--no-interaction`, protože Travis si s Composerem neumí povídat. Použijeme i `--prefer-source` kvůli omezenému počtu požadavků na GitHub API. + +Composer je již v Travisu nainstalován, ale my chceme použít nejnovější verzi, proto v bloku `before_install` provedeme jeho update. + +/-- +before_install: + - composer self-update + +install: + - composer install --no-interaction --prefer-source +\-- + +Matice testů +------------ + +Na základě předchozích údajů je vytvořena testovací matice, tedy varianty prostředí, ve kterých budou testy spuštěny (v našem příkladě 10 variant). Nastavení matice je umožněno v bloku `matrix`. + +Chceme-li některou z variant vyřadit, využijeme blok `exclude`. Nebudeme chtít spouštět testy běžných verzí PHP s parametrem `-p hhvm` a naopak pro prostředí s HHVM nebudeme testy pouštět s binárkou `php-cgi`. + +/-- +matrix: + exclude: + - php: 5.3.3 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.4 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.5 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.6 + env: TESTER_PHP_BIN="hhvm" + + - php: hhvm + env: TESTER_PHP_BIN="php-cgi" +\-- + +Aby testování bylo označeno Travisem jako úspěšné, musí testy projít ve všech prostředích. Pokud nechceme, aby výsledek některé z nich ovlivňovalo, můžeme to deklarovat v bloku `allow_failures`. V našem případě nám nebude vadit, pokud neprojdou testy na HHVM. + +/-- +matrix: + allow_failures: + - php: hhvm +\-- + +.[note] +Všimněte si, že jsme uvedli pouze verzi php. Travis se zachová tak, že do celkového výsledku nezahrne všechny kombinace s verzí `hhvm`. + +Pokud nyní testy na HHVM selžou, ale v jiných prostředích projdou, bude i celý build označen jako procházející. + +Spouštění testů +--------------- + +Testy se spouštějí v sekci `script`, kde stačí zavolat tester. Předpokládejme, že testy jsou umístěny ve složce `tests/` a používáte vlastní `php.ini` umístěné ve složce s testy. Pomocí `-s` si necháme vypsat informace o přeskočených testech. +Jako binárku nastavíme v parametru `-p` hodnotu proměnné `TESTER_PHP_BIN`, kterou jsme si nastavili v bloku `env`. + +/-- +script: + - ./vendor/bin/tester -p $TESTER_PHP_BIN -s -c ./tests/php.ini ./tests +\-- + +Když se něco pokazí +------------------- + +Blok `after_failure` se provede, pokud testy selžou. Tester při chybné aserci ukládá aktuální obsah proměnných do souborů `*.actual`. V tomto bloku si je můžeme vypsat. + +/-- +after_failure: + # Vytiskne obsah souborů *.actual + - for i in $(find ./tests -name \*.actual); do echo "--- $i"; cat $i; echo; echo; done +\-- + +Nastavení dalších služeb +------------------------ + +Travis nám umožňuje zapnout další služby. Například Redis server na který ukládáte cache. + +/-- +services: + - redis-server +\-- + +Inicializace databáze: +---------------------- + +Databáze MySQL je již předinstalována. Běží na adrese `127.0.0.1` a přihlásit se můžete na účet `travis` nebo `root` bez hesla. Pokud byste chtěli spouštět integrační testy, můžete si do ni naimportovat testovací databázi, kterou máte například v souboru `tests/testbase.sql`: + +/-- +before_script: + - mysql -u root -e 'CREATE DATABASE testbase;' + - mysql -u root testbase < tests/testbase.sql +\-- + + +Výsledný soubor +--------------- + +Celý `.travis.yml` pak vypadá takto: + +/-- +language: php + +php: + - 5.3.3 + - 5.4 + - 5.5 + - 5.6 + - hhvm + +env: + - TESTER_PHP_BIN="php-cgi" + - TESTER_PHP_BIN="hhvm" + +matrix: + allow_failures: + - php: hhvm + + exclude: + - php: 5.3.3 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.4 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.5 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.6 + env: TESTER_PHP_BIN="hhvm" + + - php: hhvm + env: TESTER_PHP_BIN="php-cgi" + +services: + - redis-server + +before_install: + - composer self-update + +install: + - composer install --no-interaction --prefer-source + +before_script: + - mysql -u root -e 'CREATE DATABASE testbase;' + - mysql -u root testbase < tests/testbase.sql + +script: + - ./vendor/bin/tester -p $TESTER_PHP_BIN -c ./tests/php.ini -s ./tests/ + +after_failure: + # Vytiskne obsah souborů *.actual + - for i in $(find ./tests -name \*.actual); do echo "--- $i"; cat $i; echo; echo; done +\-- + +Integrace s GitHubem +==================== + +Jak již bylo zmíněno dříve, Travis je integrován do prostředí GitHubu. Aby mohly být testy spouštěny ve správný okamžik, je potřeba nastavit tzv. Webhook, který informuje Travis o změně ve vašem repozitáři. + +Nastavení Webhooku +------------------ + +Nejprve je potřeba se přihlásit pomocí vašeho GitHub účtu. To provedete na [hlavní stránce |http://travis-ci.org/] pomocí odkazu `Sign in`. Po synchronizaci uvidíte repozitáře, ke kterým máte přístup, a u nich jednoduchý přepínač. Přepnutím do polohy `ON` zapnete hook. + +Travis nyní po každém pushnutém commitu nebo po vytvoření pull-requestu zařadí váš repozitář do testovací fronty a po chvilce čekání budou spuštěny testy. + +Status obrázek +-------------- + +Můžete si dokonce nechat [vygenerovat obrázek |http://docs.travis-ci.com/user/status-images/], který informuje o stavu vašeho repozitáře. Ten pak můžete vložit například do svého readme.md. + +Vynechání testů u commitu +------------------------- + +Některé commity není nutné testovat. Uveďte kdekoliv v commit message parametr `[ci skip]` a Travis bude tento commit ignorovat. \ No newline at end of file diff --git a/en/@docmenu.texy b/en/@docmenu.texy index 0aca0b3135..ae5d278726 100644 --- a/en/@docmenu.texy +++ b/en/@docmenu.texy @@ -20,7 +20,7 @@ - [Image Manipulation |images] - [Caching] - [Localization] -- [Testing] +- [Testing], [Continuous integration |testing-with-travis] - [Pagination] - [Auto-loading] - [Browsing files on disk |finder] diff --git a/en/testing-with-travis.texy b/en/testing-with-travis.texy new file mode 100644 index 0000000000..614062f256 --- /dev/null +++ b/en/testing-with-travis.texy @@ -0,0 +1,246 @@ +Continuous integration with Nette Tester +**************************************** + +/--div .[perex] + +You did it. You have covered your code with tests and now you can trust you code. Actually, you can't. One day, you will forget to run the tests, deploy to production and get an angry call from your boss later. This needn't happen if you use contrinuous integration. In this tutorial you will learn how to setup Nette/Tester with Travis CI. + +- configuring testing environment +- installing dependencies using Composer +- running tests using Nette/Tester +- setting up other services +- [TL;DR |#Result] +- GitHub integration +\-- + +How Travis CI works +=================== + +Travis CI((Continuous Integration)) ("Travis") is a very popular service for hosted [continuous integration](http://en.wikipedia.org/wiki/Continuous_Integration). The service is free of charge((Charged for private repositories.)) and offers automated execution of your tests after pushing to your repository. It is also fully integrated with GitHub. + +In order to configure Travis, you need to add a file named `.travis.yml` to the root of your repository. The file consists of sections described later in this tutorial. None of the sections is mandatory, however if we leave out the `script` section, Travis will attempt to run `phpunit`. + +The sections are executed in following order: +- `before_install` +- `install` +- `before_script` +- `script` (jediný povinný) +- `after_success` or `after_failure` +- `after_script` + +.[caution] +`.travis.yml` allows space indentation only. You can use [validator |http://lint.travis-ci.org/] to check your file. + +For more see [official documentation |http://docs.travis-ci.com]. + +Setting up .travis.yml +====================== + +Language +-------- + +First of all, you need to tell Travis which language environment to select for your project. You can do so using `language: php` option. You can specify for which PHP versions will the tests be executed. Not introducing patch version((The third version number)) tells Travis to use the latest available. + +/-- +language: php + +php: + - 5.3.3 + - 5.4 + - 5.5 + - 5.6 + - hhvm +\-- + +Environment variables +--------------------- + +You can instruct Travis to do multiple runs with different sets of environment variables values. To do so, add `env` key. Each bullet is understood as a different environment and tests are run seperately. We are going to use `TESTER_PHP_BIN` later in the file to run tester with `-p hhvm` option in HHVM environment. + +/-- +env: + - TESTER_PHP_BIN="php-cgi" + - TESTER_PHP_BIN="hhvm" +\-- + +Combination of five php versions and two environment variations generates total of 10 runs. + +Dependency installation +----------------------- + +.[note] +This tutorial assumes that you use Composer for managing your project's dependencies and that you require nette/tester in dev section. For more information see [tutorial on Composer |composer]. + +In order to install your dependencies, use `install` section. Each bullet means single command. Composer installs your dev dependencies by default. You should use `--no-interaction` so composer doesn't ask questions Travis can't answer. You should also use `--prefer-source`. It prevents your tests from randomly failing if you run out of limited amount of GitHub API requests. + +If you want to use the latest build, update Composer in `before_install` section. + +/-- +before_install: + - composer self-update + +install: + - composer install --no-interaction --prefer-source +\-- + +Build matrix +------------ + +Depending on the configuration above, a build matrix is generated. The matrix contains all combinations of environment settings. A single combination is called a job and is run separately. You can modify the matrix in `matrix` section. + +If you want to exclude a job, use `exclude` key. In our case, we don't want to use `-p hhvm` parameter for standard PHP versions and `-p php-cgi` for HHVM. + +/-- +matrix: + exclude: + - php: 5.3.3 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.4 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.5 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.6 + env: TESTER_PHP_BIN="hhvm" + + - php: hhvm + env: TESTER_PHP_BIN="php-cgi" +\-- + +Travis shows the build as passing only if every single job pass. However, you can define jobs that are allowed to fail without causing the whole build to shown as failed. To do so, declare `allow_failures`. For our sake, we allow HHVM to fail. + +/-- +matrix: + allow_failures: + - php: hhvm +\-- + +.[note] +Notice that when allowing failures, we only specified php version, not environment variables. This means all jobs with hhvm version will be allowed to fail, nevermind the environment variables values. It works with `exclude` aswell. + +Running the tests +----------------- + +Tests are run in `script` section, where you only need to execute Tester. Let's assume your tests are in `tests/` folder and you provide your own `php.ini` in the same folder. Additionaly, tell Tester to display information about skipped tests with `-s` option and to use value of earlier declared `TESTER_PHP_BIN` as PHP binary with `-p` option. + +/-- +script: + - ./vendor/bin/tester -p $TESTER_PHP_BIN -s -c ./tests/php.ini ./tests +\-- + +If test fails +------------- + +Section `after_failure` is executed if a test fails. Tester stores actual value of variables in case of assertion fail. We will use this section to print the actual values. + +/-- +after_failure: + # Prints *.actual files content + - for i in $(find ./tests -name \*.actual); do echo "--- $i"; cat $i; echo; echo; done +\-- + +Setting up other services: +-------------------------- + +Travis comes with multiple popular services (e.g. MySQL) pre-installed. However, if you need to use for example Redis storage, you can tell Travis in `services` section. + +/-- +services: + - redis-server +\-- + +Database initialization: +------------------------ + +MySQL runs on `127.0.0.1` and you can log in using `travis` or `root` as username. Password is not required. You can import your database in `before_script` section. Let's say your database set-up script is in `tests/testbase.sql`. + +/-- +before_script: + - mysql -u root -e 'CREATE DATABASE testbase;' + - mysql -u root testbase < tests/testbase.sql +\-- + + +Result +------ + +The `.travis.yml` should look something like this by now: + +/-- +language: php + +php: + - 5.3.3 + - 5.4 + - 5.5 + - 5.6 + - hhvm + +env: + - TESTER_PHP_BIN="php-cgi" + - TESTER_PHP_BIN="hhvm" + +matrix: + allow_failures: + - php: hhvm + + exclude: + - php: 5.3.3 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.4 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.5 + env: TESTER_PHP_BIN="hhvm" + + - php: 5.6 + env: TESTER_PHP_BIN="hhvm" + + - php: hhvm + env: TESTER_PHP_BIN="php-cgi" + +services: + - redis-server + +before_install: + - composer self-update + +install: + - composer install --no-interaction --prefer-source + +before_script: + - mysql -u root -e 'CREATE DATABASE testbase;' + - mysql -u root testbase < tests/testbase.sql + +script: + - ./vendor/bin/tester -p $TESTER_PHP_BIN -c ./tests/php.ini -s ./tests/ + +after_failure: + # Prints *.actual files content + - for i in $(find ./tests -name \*.actual); do echo "--- $i"; cat $i; echo; echo; done +\-- + +GitHub integration +================== + +As mentioned above, Travis is integrated with GitHub. However, you need to specify which repositories are to be tested. This is done using Webhook which notifies Travis about changes in your repository. + +Activating Webhook +------------------ + +First, go to [Travis CI |http://travis-ci.org/] and sign in with your GitHub account. After synchronizing your account, you`ll see all repositories you have access to. Flip switch to ON for all repositories you'd like to enable. + +Travis will now add your repository to queue after every pushed commit or created pull-request. After a short while, your repository will be tested. + +Status image +------------ + +Travis can [generate a status image |http://docs.travis-ci.com/user/status-images/] for you. You can embed this icon into your `README.md` file for example. + +Skipping commit +--------------- + +Some commits don't need testing. You can add `[skip ci]` somewhere in your commit message and Travis will ingore the commit. \ No newline at end of file