Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 203 lines (135 sloc) 9.907 kb
709b7fa @mageekguy Remove typo in README.
authored
1 # *atoum*
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
2
3 ## Un framework de tests unitaires pour PHP simple, moderne et intuitif !
4
1f9a370 @mageekguy Add paragraph (again) in README.markdown.
authored
5 Tout comme SimpleTest ou PHPUnit, *atoum* est un framework de tests unitaires spécifique au langage [PHP](http://www.php.net).
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
6 Cependant, il a la particularité d'avoir été conçu dès le départ pour :
7
8 * Être *Rapide* à mettre en œuvre ;
9 * *Simplifier* le développement des tests ;
10 * Permettre l'écriture de tests unitaires *fiables, lisibles et explicites* ;
11
f98a9d9 @mageekguy Remove typo.
authored
12 Pour cela, il utilise massivement les possibilités offertes par *PHP 5.3*, pour fournir au développeur *une nouvelle façon* d'écrire des tests unitaires.
1f9a370 @mageekguy Add paragraph (again) in README.markdown.
authored
13 Ainsi, il s'installe et s'intégre très facilement dans un projet puisqu'il se présente sous la forme d'une *unique archive PHAR*, qui est le seul et unique point d'entrée du développeur.
14 De plus, grâce à son *interface fluide*, il permet la rédaction des tests unitaires en langage quasiment naturel.
15 Il facilite également la mise en œuvre du bouchonnage au sein des tests, grâce à une utilisation intelligente des *fonctions anonymes et des fermetures*.
16 *atoum* propose nativement et par défaut d'exécuter chaque test unitaire au sein d'un processus [PHP](http://www.php.net) séparé afin d'en garantir *l'isolation*.
17 Et évidemment, son utilisation dans le cadre d'un processus d'intégration continue ne pose aucun problème, et de part sa conception, il est très facile de l'adapter à des besoins spécifiques.
18 *atoum* réalise de plus tout cela sans sacrifier les performances, puisqu'il a été développé pour avoir une empreinte mémoire réduite tout en autorisant une exécution rapide des tests.
19 Il est de plus à même de générer des rapports d'exécution des tests unitaires au format Xunit, ce qui lui permet d'être compatible avec des outils d'intégration continue tel que [Jenkins](http://jenkins-ci.org/).
20 *atoum* permet de plus de générer des rapports de couverture de code, afin de permettre la supervision des tests unitaires.
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
21 Enfin, même s'il est actuellement développé principalement sous UNIX, il est également fonctionnel sous Windows.
22
277af22 @mageekguy Remove typo in README.
authored
23 ## Prérequis pour utiliser *atoum*
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
24
1f9a370 @mageekguy Add paragraph (again) in README.markdown.
authored
25 *atoum* nécéssite *absolument* une version de PHP supérieure ou égale à 5.3 pour fonctionner.
26 Si vous souhaitez utiliser *atoum* via son archive PHAR, il faut de plus que [PHP](http://www.php.net] dispose du module `phar`, Normalement disponible par défaut.
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
27 Afin de vérifier que vous disposez de ce module sous UNIX, il vous suffit d'exécuter la commande suivante dans votre terminal :
28
29 # php -m | grep -i phar
30
1f9a370 @mageekguy Add paragraph (again) in README.markdown.
authored
31 Si `Phar` ou un équivalent s'affiche, le module est installé.
32 La génération des rapports au format Xunit nécessite le module `xml`.
f98a9d9 @mageekguy Remove typo.
authored
33 Afin de vérifier que vous disposez de ce module sous UNIX, il vous suffit d'exécuter la commande suivante dans votre terminal :
34
35 # php -m | grep -i xml
36
37 Si `Xml` ou un équivalent s'affiche, le module est installé.
38
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
39 L'extension [Xdebug](http://xdebug.org/) est quand à elle requise si vous désirer surveiller le taux de couverture de votre code par vos tests unitaires.
f98a9d9 @mageekguy Remove typo.
authored
40 Afin de vérifier que vous disposez de ce module sous UNIX, il vous suffit d'exécuter la commande suivante dans votre terminal :
41
42 # php -m | grep -i xdebug
43
44 Si `Xdebug` ou un équivalent s'affiche, le module est installé.--
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
45
46 ## Un framework de tests unitaires opérationnel en 5 minutes !
47
48 ### Étape 1 : Installez *atoum*
49
1f9a370 @mageekguy Add paragraph (again) in README.markdown.
authored
50 Il suffit pour cela que vous téléchargiez [son archive PHAR](http://downloads.atoum.org/nightly/mageekguy.atoum.phar) et la stockiez à l'emplacement de votre choix, par exemple dans `/path/to/project/tests/mageekguy.atoum.phar`.
51 Cette archive PHAR contient la dernière version de développement ayant passé avec succès l'intégralité des tests unitaires d'*atoum*.
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
52 Le code source d'*atoum* est également disponible via [son dépôt sur github](https://github.com/mageekguy/atoum).
53
54 ### Étape 2 : Écrivez votre test
55
56 À l'aide de votre éditeur favori, créé le fichier `path/to/project/tests/units/helloWorld.php` et ajoutez-y le code suivant :
57
58 <?php
59
60 namespace vendor\project\tests\units;
61
751c2d7 @mageekguy Improve autorunner and field's report.
authored
62 require_once 'path/to/mageekguy.atoum.phar';
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
63
751c2d7 @mageekguy Improve autorunner and field's report.
authored
64 include_once 'path/to/project/classes/helloWorld.php';
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
65
751c2d7 @mageekguy Improve autorunner and field's report.
authored
66 use mageekguy\atoum;
67 use vendor\project;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
68
69 class helloWorld extends atoum\test
70 {
71 public function testSay()
72 {
73 $helloWorld = new project\helloWorld();
74
75 $this->assert
76 ->string($helloWorld->say())->isEqualTo('Hello World !')
77 ;
78 }
79 }
80
81 ?>
82
83 ### Étape 3 : Exécutez votre test en ligne de commande
84
85 Lancer votre terminal et exécutez l'instruction suivante :
86
87 # php path/to/test/file[enter]
88
89 Vous devez obtenir le résultat suivant, ou équivalent :
90
91 > Atoum version XXX by Frédéric Hardy.
92 Error: Unattended exception: Tested class 'vendor\project\helloWorld' does not exist for test class 'vendor\project\tests\units\helloWorld'
93
94 ### Étape 4 : Écrivez la classe correspondant à votre test
95
96 À nouveau à l'aide de votre éditeur favori, créé le fichier `path/to/project/classes/helloWorld.php` et ajoutez-y le code suivant :
97
98 <?php
99
100 namespace vendor\project;
101
102 class helloWorld
103 {
104 public function say()
105 {
106 return 'Hello World !';
107 }
108 }
109
110 ?>
111
112 ### Étape 5 : Exécutez à nouveau votre test
113
114 Toujours votre terminal, exécutez une nouvelle fois l'instruction suivante :
115
116 # php path/to/test/file[enter]
117
118 Vous devez cette fois obtenir le résultat suivant, ou équivalent :
119
120 > Atoum version 288 by Frédéric Hardy.
121 > Run vendor\project\tests\units\helloWorld...
122 [S___________________________________________________________][1/1]
123 => Test duration: 0.00 second.
124 => Memory usage: 0.25 Mb.
125 > Total test duration: 0.00 second.
126 > Total test memory usage: 0.25 Mb.
127 > Code coverage value: 100.00%
128 > Running duration: 0.08 second.
129 > Success (1 test, 1 method, 2 assertions, 0 error, 0 exception) !
130
131 ### Étape 6 : Complétez vos tests et recommencez le cycle à partir de l'étape 3
132
133 <?php
134
135 namespace vendor\project\tests\units;
136
498dbf9 @mageekguy Add information in troubleshooting section of README about __COMPILER…
authored
137 require_once 'path/to/mageekguy.atoum.phar';
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
138
751c2d7 @mageekguy Improve autorunner and field's report.
authored
139 include_once 'path/to/project/classes/helloWorld.php';
140
141 use mageekguy\atoum;
142 use vendor\project;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
143
144 class helloWorld extends atoum\test
145 {
146 public function test__construct()
147 {
148 $helloWorld = new project\helloWorld();
149
150 $this->assert
151 ->string($helloWorld->say())->isEqualTo('Hello !')
152 ->string($helloWorld->say($name = 'Frédéric Hardy'))->isEqualTo('Hello ' . $name . ' !')
153 ;
154 }
155 }
156
157 ?>
158
159 ## Pour aller plus loin
160
1f9a370 @mageekguy Add paragraph (again) in README.markdown.
authored
161 La documentation d'*atoum* est en cours de rédaction et la seule ressource disponible actuellement est le présent document.
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
162 Cependant, si vous désirez explorer plus en avant et immédiatement les possibilités d'*atoum*, nous vous conseillons :
163
164 * D'exécuter dans votre terminal soit la commande `php mageekguy.atoum.phar -h`, soit `php scripts/runner.php -h` ;
4376a42 @mageekguy Remove typo in README.markdown.
authored
165 * D'explorer le contenu du répertoire `configurations` des sources d'*atoum*, car il contient des exemples de fichier de configuration ;
166 * D'explorer le contenu du répertoire `tests/units/classes` des sources d'*atoum*, car il contient l'ensemble de ses tests unitaires ;
3911913 @mageekguy Remove typo (again) in README.markdown.
authored
167 * De lire [les supports de conférence](http://www.slideshare.net/impossiblium/atoum-le-framework-de-tests-unitaires-pour-php-53-simple-moderne-et-intuitif) à son sujet disponible en ligne ;
4f46d01 @mageekguy Add information about support.
authored
168 * De rejoindre le canal IRC *##atoum* sur le réseau *freenode* ;
169 * De poser vos questions par courrier électronique à l'adresse *support[AT]atoum(DOT)org* ;
29133d9 @mageekguy Add troubleshootings section in FAQ and README.
authored
170
171 ## Dépannage
172
173 ### L'archive PHAR de *atoum* semble ne pas fonctionner
174
175 Dans ce cas, la première chose à faire est de vous assurer que vous disposez de la dernière version de l'archive.
176 Pour cela, il suffit de la [télécharger](http://downloads.atoum.org/nightly/mageekguy.atoum.phar) à nouveau.
ec8f8a0 @mageekguy Remove typo in troubleshootings section in README.
authored
177 Si elle ne fonctionne toujours pas, exécutez dans un terminal la commande suivante :
29133d9 @mageekguy Add troubleshootings section in FAQ and README.
authored
178
179 # php -n mageekguy.atoum.phar -v
180
181 Si vous obtenez le numéro de version d'atoum, c'est que le problème provient de votre configuration de PHP.
182 Dans la plupart des cas, il s'agit d'extensions, qui sont soit incompatible avec le format PHAR, soit qui empêche l'exécution des archives PHAR par sécurité.
f1f45bf @mageekguy Improve troubleshootings section in README.
authored
183 L'extension `ioncube` semble par exemple incompatible avec les archives PHAR et il faut donc la désactiver si vous l'utilisez, en commantant dans votre `php.ini` la ligne suivante en la préfixant par le caractère `;` :
184
185 zend_extension = /path/to/ioncube_loader*.*
186
187 L'extension `suhosin` empêche quand à elle l'exécution des PHAR, et il faut donc modifier sa configuration par défaut afin de pouvoir utiliser *atoum*, en ajoutant la ligne suivante dans votre fichier `php.ini` :
29133d9 @mageekguy Add troubleshootings section in FAQ and README.
authored
188
189 suhosin.executor.include.whitelist="phar"
190
5944651 @mageekguy Add informations about detect_unicode in FAQ and README.
authored
191 Enfin, si l'exécution d'*atoum* provoque à l'écran l'affichage de caractères du style `???%`, c'est que la directive `detect_unicode` de votre fichier `php.ini` est à 1.
192 Pour résoudre le problème, il suffit donc de la passer à 0 en éditant votre fichier `php.ini` ou en exécutant *atoum* à l'aide de la commande suivante :
193
9e87ad5 @mageekguy Remove typo in README.
authored
194 # php -d detect_unicode=0 mageekguy.atoum.phar [options]
5944651 @mageekguy Add informations about detect_unicode in FAQ and README.
authored
195
196 Si ces trois manipulations ne permettent pas à *atoum* de fonctionner, nous vous invitons à envoyer un courrier électronique à l'adresse *support[AT]atoum(DOT)org*, décrivant précisément votre configuration ainsi que votre problème.
29133d9 @mageekguy Add troubleshootings section in FAQ and README.
authored
197 Vous pouvez également demander de l'aide aux développeurs d'*atoum* sur le canal IRC ##atoum sur le réseau *freenode*.
498dbf9 @mageekguy Add information in troubleshooting section of README about __COMPILER…
authored
198
ffcb352 @mageekguy Improve README.
authored
199 ### Error: Constant __COMPILER_HALT_OFFSET__ already defined /path/to/mageekguy.atoum.phar
498dbf9 @mageekguy Add information in troubleshooting section of README about __COMPILER…
authored
200
201 Cette erreur est provoquée par le fait que l'archive PHAR de *atoum* est incluse à au moins un endroit dans votre code à l'aide de `include` ou `require`.
202 Pour résoudre ce problème, il suffit donc d'inclure l'archive uniquement via `include_once` ou `require_once`, afin d'empêcher qu'elle ne soit incluse plusieurs fois.
Something went wrong with that request. Please try again.