Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 230 lines (158 sloc) 11.11 kb
709b7fa @mageekguy Remove typo in README.
authored
1 # *atoum*
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
2
a7c2e95 @bobey There is no space between a word and an exclamation mark in english... I...
bobey authored
3 ## A simple, modern and intuitive unit testing framework for PHP!
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
4
4cd8d89 @mageekguy Typo.
authored
5 Just like SimpleTest or PHPUnit, *atoum* is a unit testing framework specific to the [PHP](http://www.php.net) language.
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
6 However, it has been designed from the start with the following ideas in mind :
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
7
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
8 * Can be implemented *rapidly* ;
9 * *Simplify* test development ;
1669e84 @mageekguy Typo.
authored
10 * Allow for writing *reliable, readable, and clear* unit tests ;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
11
1669e84 @mageekguy Typo.
authored
12 To accomplish that, it massively uses capabilities provided by *PHP 5.3*, to give the developer *a whole new way* of writing unit tests.
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
13 Therefore, it can be installed and integrated inside an existing project extremely easily, since it is only a *single PHAR archive*, which is the one and only entry point for the developper.
1669e84 @mageekguy Typo.
authored
14 Also, thanks to its *fluid interface*, it allows for writing unit tests in a fashion close to natural language.
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
15 It also makes it easier to implement stubbing within tests, thanks to intelligent uses of *anonymous functions and closures*.
1669e84 @mageekguy Typo.
authored
16 *atoum* natively, and by default, performs the execution of each unit test within a separate [PHP](http://www.php.net) process, to warrant *isolation*.
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
17 Of course, it can be used seamlessly for continuous integration, and given its design, it can be made to cope with specific needs extremely easily.
036c688 @chadburrus developped -> developed
chadburrus authored
18 *atoum* also accomplishes all of this without affecting performance, since it has been developed to boast a reduced memory footprint while allowing for hastened test execution.
1669e84 @mageekguy Typo.
authored
19 It can also generate unit test execution reports in the Xunit format, which makes it compatible with continuous integration tools such as [Jenkins](http://jenkins-ci.org/).
20 *atoum* also generates code coverage reports, in order to make it possible to supervise unit tests.
036c688 @chadburrus developped -> developed
chadburrus authored
21 Finally, even though it is developed mainly on UNIX, it can also work on Windows.
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
22
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
23 ## Prerequisites to use *atoum*
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
24
5800dbf @chadburrus superior -> later
chadburrus authored
25 *atoum* absolutely requires *PHP 5.3* or later to work.
d700ac4 @geraldcroes Typo in last commit
geraldcroes authored
26 Should you want to use *atoum* using its PHAR archive, you also need [PHP](http://www.php.net) to be able to access the `phar` module, which is normally available by default.
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
27 On UNIX, in order to check whether you have this module or not, you just need to run the following command in your terminal :
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
28
29 # php -m | grep -i phar
30
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
31 If `Phar` or equivalent gets displayed, then the module is properly installed.
32 Generating reports in the Xunit format requires the `xml` module.
33 On UNIX, in order to check whether you have this module or not, you just need to run the following command in your terminal :
f98a9d9 @mageekguy Remove typo.
authored
34
35 # php -m | grep -i xml
36
f5f613a @mageekguy Typo.
authored
37 If `Xml` or equivalent gets displayed, then the module is properly installed.
1669e84 @mageekguy Typo.
authored
38 Should you wish to monitor the coverage rate of your code by the unit tests, the [Xdebug](http://xdebug.org/) will be required.
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
39 On UNIX, in order to check whether you have this module or not, you just need to run the following command in your terminal :
f98a9d9 @mageekguy Remove typo.
authored
40
41 # php -m | grep -i xdebug
42
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
43 If `Xdebug` or equivalent gets displayed, then the module is properly installed.
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
44
a7c2e95 @bobey There is no space between a word and an exclamation mark in english... I...
bobey authored
45 ## A unit testing framework that can be made operational in 5 minutes!
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
46
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
47 ### Step 1 : Install *atoum*
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
48
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
49 You just have to download [its PHAR archive](http://downloads.atoum.org/nightly/mageekguy.atoum.phar) and store it where you wish, for example under `/path/to/project/tests/mageekguy.atoum.phar`.
1669e84 @mageekguy Typo.
authored
50 This PHAR archive contains the latest development version to pass the totality of *atoum*'s unit tests.
8a71168 @mageekguy Add information about --testIt in README.
authored
51 *atoum*'s source code is also available via [the github repository](https://github.com/mageekguy/atoum).
52 To check if *atoum* works correctly with your configuration, you can execute all its unit tests.
53 To do that, you just need to run the following command in your terminal :
54
55 # php mageekguy.atoum.phar --testIt
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
56
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
57 ### Step 2 : Write your tests
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
58
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
59 Using your preferred text editor, create the file `path/to/project/tests/units/helloWorld.php` and add the following code :
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
60
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
61 ``` php
62 <?php
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
63
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
64 namespace vendor\project\tests\units;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
65
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
66 require_once 'path/to/mageekguy.atoum.phar';
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
67
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
68 include 'path/to/project/classes/helloWorld.php';
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
69
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
70 use \mageekguy\atoum;
71 use \vendor\project;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
72
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
73 class helloWorld extends atoum\test
74 {
75 public function testSay()
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
76 {
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
77 $helloWorld = new project\helloWorld();
78
0804558 @mageekguy Remove useless call to ->assert.
authored
79 $this->string($helloWorld->say())->isEqualTo('Hello World!')
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
80 ;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
81 }
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
82 }
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
83
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
84 ?>
85 ```
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
86
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
87 ### Step 3 : Run your test with the commandline
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
88
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
89 Launch your terminal and run the following command :
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
90
91 # php path/to/test/file[enter]
92
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
93 You should get the following result, or something equivalent :
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
94
f0804fa @mageekguy Use 'atoum' instead of 'Atoum'.
authored
95 > atoum version XXX by Frédéric Hardy.
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
96 Error: Unattended exception: Tested class 'vendor\project\helloWorld' does not exist for test class 'vendor\project\tests\units\helloWorld'
97
64149c6 @chadburrus you -> your
chadburrus authored
98 ### Step 4 : Write the class corresponding to your test
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
99
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
100 Using again your preferred text editor, create the file `path/to/project/classes/helloWorld.php` and add the following code :
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
101
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
102 ``` php
103 <?php
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
104
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
105 namespace vendor\project;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
106
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
107 class helloWorld
108 {
109 public function say()
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
110 {
a7c2e95 @bobey There is no space between a word and an exclamation mark in english... I...
bobey authored
111 return 'Hello World!';
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
112 }
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
113 }
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
114
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
115 ?>
629ec14 @mageekguy Typo.
authored
116 ```
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
117
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
118 ### Step 5 : Run your test once more
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
119
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
120 In the same terminal, run the following command once again :
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
121
122 # php path/to/test/file[enter]
123
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
124 You should get the following result, or something equivalent :
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
125
f0804fa @mageekguy Use 'atoum' instead of 'Atoum'.
authored
126 > atoum version 288 by Frédéric Hardy.
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
127 > Run vendor\project\tests\units\helloWorld...
128 [S___________________________________________________________][1/1]
129 => Test duration: 0.00 second.
130 => Memory usage: 0.25 Mb.
131 > Total test duration: 0.00 second.
132 > Total test memory usage: 0.25 Mb.
133 > Code coverage value: 100.00%
134 > Running duration: 0.08 second.
135 > Success (1 test, 1 method, 2 assertions, 0 error, 0 exception) !
136
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
137 ### Step 6 : Complete your tests and restart the cycle from Step 3
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
138
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
139 ``` php
140 <?php
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
141
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
142 namespace vendor\project\tests\units;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
143
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
144 require_once 'path/to/mageekguy.atoum.phar';
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
145
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
146 include_once 'path/to/project/classes/helloWorld.php';
751c2d7 @mageekguy Improve autorunner and field's report.
authored
147
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
148 use mageekguy\atoum;
149 use vendor\project;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
150
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
151 class helloWorld extends atoum\test
152 {
153 public function test__construct()
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
154 {
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
155 $helloWorld = new project\helloWorld();
156
0804558 @mageekguy Remove useless call to ->assert.
authored
157 $this
a7c2e95 @bobey There is no space between a word and an exclamation mark in english... I...
bobey authored
158 ->string($helloWorld->say())->isEqualTo('Hello!')
159 ->string($helloWorld->say($name = 'Frédéric Hardy'))->isEqualTo('Hello ' . $name . '!')
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
160 ;
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
161 }
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
162 }
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
163
766131a @mageekguy Use highlighting in README.markdown, thanks to stealth35.
authored
164 ?>
165 ```
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
166
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
167 ## To go further
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
168
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
169 *atoum*'s documentation is still being written, and the only available resource right now is the current document.
170 However, if you want to further explore immediately *atoum*'s possibilities, we recommend :
41f7cb8 @mageekguy Remove README and add README.markdown.
authored
171
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
172 * Running in your terminal, either the command `php mageekguy.atoum.phar -h`, or the command `php scripts/runner.php -h` ;
173 * Exploring the contents of the `configurations` directory in *atoum*'s source, as it contains configuration file samples ;
1669e84 @mageekguy Typo.
authored
174 * Exploring the contents of the `tests/unit/classes` directory in *atoum*'s source, as it contains all of the unit tests ;
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
175 * Read the [conference supports](http://www.slideshare.net/impossiblium/atoum-le-framework-de-tests-unitaires-pour-php-53-simple-moderne-et-intuitif) about it, available online ;
6b7bfc4 @mageekguy Add link to the wiki in README.markdown.
authored
176 * Read the (french) [wiki](https://github.com/mageekguy/atoum/wiki) ;
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
177 * Join the IRC channel *##atoum* on the *freenode* network ; * Ask questions by e-mail at the address *support[AT]atoum(DOT)org* ;
29133d9 @mageekguy Add troubleshootings section in FAQ and README.
authored
178
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
179 ## Troubleshooting
29133d9 @mageekguy Add troubleshootings section in FAQ and README.
authored
180
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
181 ### *atoum*'s PHAR archive seems to not be working
29133d9 @mageekguy Add troubleshootings section in FAQ and README.
authored
182
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
183 In this case, the first thing you will want to do is confirm whether you have the latest version of the archive.
184 You just need to [download](http://downloads.atoum.org/nightly/mageekguy.atoum.phar) it again.
185 If it still doesn't work, run the following command in a terminal window :
29133d9 @mageekguy Add troubleshootings section in FAQ and README.
authored
186
187 # php -n mageekguy.atoum.phar -v
188
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
189 If you get *atoum*'s version number, then the problem is coming from your PHP configuration.
190 In most cases, the cause would be within extensions, that might be incompatible with the PHAR format, or that would prevent executing PHAR archives as a security measure.
191 The `ioncube` extension for instance seems incompatible with PHAR archives, and you must therefore deactivate it if you are using it, by commenting the following line out of your `php.ini`, by prefixing it with the `;` character :
f1f45bf @mageekguy Improve troubleshootings section in README.
authored
192
193 zend_extension = /path/to/ioncube_loader*.*
194
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
195 The `suhosin` extension prevents executing PHAR archives, therefore its default configuration must be modified in order to be able to use *atoum*, by adding the following line in your `php.ini` file :
29133d9 @mageekguy Add troubleshootings section in FAQ and README.
authored
196
197 suhosin.executor.include.whitelist="phar"
198
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
199 Finally, if running *atoum* causes the screen to display characters looking like `???%`, this would be because the `detect_unicode` directive inside your `php.ini` file is set to 1.
200 To fix the problem, you just need to set it to 0 by editing your `php.ini` file or by running *atoum* with the following command :
5944651 @mageekguy Add informations about detect_unicode in FAQ and README.
authored
201
9e87ad5 @mageekguy Remove typo in README.
authored
202 # php -d detect_unicode=0 mageekguy.atoum.phar [options]
5944651 @mageekguy Add informations about detect_unicode in FAQ and README.
authored
203
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
204 If these three operations do not allow *atoum* to work, we suggest you send an e-mail to the address *support[AT]atoum(DOT)org*, describing in detail your configuration and your problem.
205 You can also ask for help from the *atoum* development staff on the IRC channel *##atoum* on the *freenode* network.
498dbf9 @mageekguy Add information in troubleshooting section of README about __COMPILER_HA...
authored
206
ffcb352 @mageekguy Improve README.
authored
207 ### Error: Constant __COMPILER_HALT_OFFSET__ already defined /path/to/mageekguy.atoum.phar
498dbf9 @mageekguy Add information in troubleshooting section of README about __COMPILER_HA...
authored
208
8bb8e9b @chadburrus nuked an unnecessary comma
chadburrus authored
209 This error comes from the fact the *atoum* PHAR archive is included in more than one place within your code using `include` or `require`.
a1efa0a @mageekguy Add english version of README, thanks to Darksoul.
authored
210 To fix this problem, you just need to include the archive by using only `include_once` or `require_once`, in order to ensure it is not included several times.
afb5dd9 @mageekguy Add informations about APC.
authored
211
212 ### APC seems not work with *atoum*
213 [APC](http://fr.php.net/manual/en/apc.configuration.php) is a free, open, and robust framework for caching and optimizing PHP intermediate code distributed under the form of a PHP extension.
214 When testing classes that use APC, you may get some failure message showing that `apc_fetch` function is unable to retrieve a value.
215 As all PHP extension, APC has some configuration options to enable it :
216
217 * `apc.enabled` whether to enable or disable APC ;
218 * `apc.enable_cli`, whether to enable or disable APC for PHP CLI ;
219
220 In order to use [APC](http://fr.php.net/manual/en/apc.configuration.php) with *atoum*, you have to set `apc.enabled` and `apc.enable_cli` to `1`, otherwise, it won't be enabled for the PHP CLI version, which is used by *atoum*.
d09ddac Added an entry to the readme to explain a workaround for the segfaults w...
Julien BIANCHI authored
221
222 ### Getting segfault when mocking objects
1a5eaf9 @mageekguy Typo.
authored
223 When using *atoum* and mocking objects, you will sometime get segfaults coming from [PHP](http://www.php.net).
224 These segfaults are caused by [XDebug](http://xdebug.org/) in version less than 2.1.0 which has problem handling reflection in some cases.--
225 To check the current version of [XDebug](http://xdebug.org/), you can run `php -v`.
226 To fix this issue, you have to update [XDebug](http://xdebug.org/) to the latest [stable version](http://xdebug.org/download.php).
02716c5 @mageekguy Typo.
authored
227 If you can't update [XDebug](http://xdebug.org/) on your system, you can still disable the extension to avoid getting segfaults.
228 To be sure that [XDebug](http://xdebug.org/) has been succefully updated or disabled, you can run `php -v`.
b78b657 @mageekguy Typo.
authored
229 When you are done updating or disabling [XDebug](http://xdebug.org/), run `php mageekguy.atoum.phar --test-it` to be sure that all the segfaults have gone and that *atoum* is working.
Something went wrong with that request. Please try again.