{"id":13622668,"url":"https://github.com/atoum/atoum","last_synced_at":"2025-04-09T02:13:26.557Z","repository":{"id":1554213,"uuid":"1942295","full_name":"atoum/atoum","owner":"atoum","description":"The modern, simple and intuitive PHP unit testing framework.","archived":false,"fork":false,"pushed_at":"2024-07-31T12:02:10.000Z","size":9137,"stargazers_count":1443,"open_issues_count":65,"forks_count":147,"subscribers_count":44,"default_branch":"main","last_synced_at":"2025-04-02T01:11:47.931Z","etag":null,"topics":["atoum","hacktoberfest","php","test","test-framework","unit-testing"],"latest_commit_sha":null,"homepage":"http://atoum.org","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atoum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-06-23T15:35:22.000Z","updated_at":"2025-03-13T10:14:46.000Z","dependencies_parsed_at":"2024-09-21T06:02:17.733Z","dependency_job_id":"3e7a414a-0c98-4c4b-bec8-4331c545c2d0","html_url":"https://github.com/atoum/atoum","commit_stats":{"total_commits":2871,"total_committers":87,"mean_commits":33.0,"dds":"0.33681644026471613","last_synced_commit":"e866f3d4ad683c35757cd73fc6da3e3d5e563667"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atoum%2Fatoum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atoum%2Fatoum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atoum%2Fatoum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atoum%2Fatoum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atoum","download_url":"https://codeload.github.com/atoum/atoum/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247962594,"owners_count":21024870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atoum","hacktoberfest","php","test","test-framework","unit-testing"],"created_at":"2024-08-01T21:01:22.471Z","updated_at":"2025-04-09T02:13:26.527Z","avatar_url":"https://github.com/atoum.png","language":"PHP","funding_links":[],"categories":["测试","测试 Testing","PHP","Table of Contents","Testing","目录","测试( Testing )","类库"],"sub_categories":["Testing","测试 Testing","测试框架","Globalization"],"readme":"![atoum's logo](resources/images/logo.png)\n\n# *atoum* [![Package version](https://img.shields.io/packagist/v/atoum/atoum.svg)](https://packagist.org/packages/atoum/atoum) [![Build Status](https://github.com/atoum/atoum/actions/workflows/unit-tests.yml/badge.svg?branch=master)](https://github.com/atoum/atoum/actions/workflows/unit-tests.yml?query=branch%3Amaster) [![Coverage Status](https://coveralls.io/repos/github/atoum/atoum/badge.svg?branch=master)](https://coveralls.io/github/atoum/atoum?branch=master) [![Lint](https://github.com/atoum/atoum/actions/workflows/lint.yml/badge.svg?branch=master)](https://github.com/atoum/atoum/actions/workflows/lint.yml?query=branch%3Amaster) [![Gitter](https://badges.gitter.im/atoum/atoum.svg)](https://gitter.im/atoum/atoum?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n\n| PHP version | atoum version       |\n|-------------|---------------------|\n| 5.3 -\u003e 5.6  | 1.x -\u003e 3.x          |\n| 7.2 -\u003e 8.1  | 4.X -\u003e 4.1          |\n| 8.x         | 4.1 \u003c 4.X (current) |\n\n## A simple, modern and intuitive unit testing framework for PHP!\n\nJust like SimpleTest or PHPUnit, *atoum* is a unit testing framework specific to the [PHP](http://www.php.net) language.\nHowever, it has been designed from the start with the following ideas in mind:\n\n* Can be implemented *rapidly*,\n* *Simplify* test development,\n* Allow for writing *reliable, readable, and clear* unit tests.\n\nTo accomplish that, it massively uses capabilities provided by *PHP*, to give the developer *a whole new way* of writing unit tests.\nTherefore, it can be installed and integrated into an existing project extremely easily, since it is only a *single PHAR archive*, which is the one and only entry point for the developer.\nAlso, thanks to its *fluent interface*, it allows for writing unit tests in a fashion close to natural language.\nIt also makes it easier to implement stubbing within tests, thanks to intelligent uses of *anonymous functions and closures*.\n*atoum* natively, and by default, performs the execution of each unit test within a separate [PHP](http://www.php.net) process, to warrant *isolation*.\nOf course, it can be used seamlessly for continuous integration, and given its design, it can be made to cope with specific needs extremely easily.\n*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.\nIt 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/).\n*atoum* also generates code coverage reports, in order to make it possible to supervise unit tests.\nFinally, even though it is developed mainly on UNIX, it can also work on Windows.\n\n## Why atoum?\n\n* *atoum* is really [easy to install](http://docs.atoum.org/en/latest/installation.html): clone it [from github](https://github.com/atoum/atoum), download [its PHAR](https://github.com/atoum/atoum/releases/download/3.2.0/atoum.phar) or simply [use composer](https://packagist.org/packages/atoum/atoum),\n* *atoum* provides a high level of security during test execution by isolating each test method in its own PHP process. Of course, this feature is available out of the box, no need to install any additional extension,\n* *atoum* runs tests in a parallelized environment making the suite run as fast as possible by taking advantage of today's multi-core CPUs,\n* *atoum* provides a [full-featured set of natural and expressive assertions](http://docs.atoum.org/en/latest/asserters.html) making tests as readable as possible. Here is an example:\n\n```php\n\u003c?php\n\n$this\n    -\u003einteger(150)\n        -\u003eisGreaterThan(100)\n        -\u003eisLowerThanOrEqualTo(200)\n;\n```\n\n* *atoum* supports a BDD-like syntax with a lot of structural keywords:\n\n```php\n\u003c?php\n\n$this\n    -\u003egiven($testedInstance = new testedClass())\n    -\u003eand($testedClass[] = $firstValue = uniqid())\n    -\u003ethen\n        -\u003esizeof($testedInstance)-\u003eisEqualTo(1)\n        -\u003estring($testedClass[0])-\u003eisEqualTo($firstValue)\n;\n```\n\n* *atoum* provides a dead simple, yet very powerful, [mock engine](http://docs.atoum.org/en/latest/chapter2.html#mock):\n\n```php\n\u003c?php\n\n$this\n    -\u003egiven($testedInstance = new testedClass())\n    -\u003eand($aMock = new \\mock\\foo\\bar()) // here a mock of the class \\foo\\bar is created dynamically\n    -\u003eand($this-\u003ecalling($aMock)-\u003edoOtherThing = true) // each call to doOtherThing() by the instance will return true\n    -\u003eand($testedInstance-\u003esetDependency($aMock))\n    -\u003ethen\n        -\u003eboolean($testedInstance-\u003edoSomething())-\u003eisTrue()\n        -\u003emock($aMock)\n            -\u003ecall('doOtherThing')-\u003ewithArguments($testedInstance)-\u003eonce() // Asserts that the doOtherThing() method of $aMock was called once\n;\n```\n\n* *atoum* provides a clear API to assert on exceptions:\n\n```php\n\u003c?php\n\n$this\n    -\u003egiven($testedInstance = new testedClass())\n    -\u003eand($aMock = new \\mock\\foo\\bar()) // here a mock of the class \\foo\\bar is created dynamically\n    -\u003eand($this-\u003ecalling($aMock)-\u003edoOtherThing-\u003ethrow = $exception = new \\exception()) // Call to doOtherThing() will throw an exception\n    -\u003eand($testedInstance-\u003esetDependency($aMock))\n    -\u003ethen\n        -\u003eexception(function() use ($testedInstance) { $testedInstance-\u003edoSomething(); })\n            -\u003eisIdenticalTo($exception)\n;\n```\n\n* *atoum* also lets you mock native PHP functions. Again, this is available out of the box:\n\n```php\n\u003c?php\n\n$this\n    -\u003egiven($this-\u003efunction-\u003esession_start = false)\n    -\u003eand($session = new testedClass())\n    -\u003ethen\n        -\u003eexception(function () use ($session) { $session-\u003estart(); })\n            -\u003eisInstanceOf('project\\namespace\\exception')\n            -\u003ehasMessage('Unable to start session')\n        -\u003efunction('session_start')-\u003ewasCalled()-\u003eonce()\n;\n```\n\n* *atoum* is able to produce several reports like TAP, clover, xUnit to be easily integrated with Jenkins or any other continuous integration tool,\n* *atoum* supports [data providers](http://docs.atoum.org/en/latest/written_help.html#data-providers),\n* *atoum* tests support autorun: just include the *atoum* runner and launch your test using `php path/to/test/file.php`,\n* *atoum*'s [configuration file](http://docs.atoum.org/en/latest/chapter3.html#configuration-files) is exclusively written in PHP (no XML, YAML or any other format) giving you the best flexibility:\n\n```php\n\u003c?php\n\n$script-\u003eaddDefaultArguments('--test-it', '-ncc');\n\n$runner-\u003eaddTestsFromDirectory(__DIR__ . '/tests/units/classes');\n\n$testGenerator = new atoum\\atoum\\test\\generator();\n$testGenerator\n    -\u003esetTestClassesDirectory(__DIR__ . '/tests/units/classes');\n    -\u003esetTestClassNamespace('atoum\\atoum\\tests\\units');\n    -\u003esetTestedClassesDirectory(__DIR__ . '/classes');\n    -\u003esetTestedClassNamespace('atoum\\atoum')\n    -\u003esetRunnerPath(__DIR__ . '/scripts/runner.php')\n;\n\n$runner-\u003esetTestGenerator($testGenerator);\n```\n\n* *atoum* provides an automatic test template generator,\n* *atoum* provides a [loop mode](http://docs.atoum.org/en/latest/chapter3.html#l-loop) to easily retrigger failed tests,\n* *atoum* is full of other interesting features that you will discover over the time.\n\n## Prerequisites to use *atoum*\n\n*atoum* absolutely requires *PHP `\u003e= 5.6.0`* or later to work.\nOn UNIX, in order to check whether you have the right PHP version, you just need to run the following command in your terminal:\n\n```sh\n$ php -v | grep -oE 'php 5\\.3\\.(?:[3-9]|[1-9][0-9])|5\\.[4-6]\\.[0-9]+|[5-8]\\.[0-9]+\\.[0-9]+'\n```\n\nIf `PHP 5.6.x` or equivalent gets displayed, then you have the right PHP version installed.\nShould 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.\nOn UNIX, in order to check whether you have this module or not, you just need to run the following command in your terminal:\n\n```sh\n$ php -m | grep -i phar\n```\n\nIf `Phar` or equivalent gets displayed, then the module is properly installed.\nGenerating reports in the Xunit format requires the `xml` module.\nOn UNIX, in order to check whether you have this module or not, you just need to run the following command in your terminal:\n\n```sh\n$ php -m | grep -i xml\n```\n\nIf `Xml` or equivalent gets displayed, then the module is properly installed.\nShould you wish to monitor the coverage rate of your code by the unit tests, the [Xdebug](http://xdebug.org/) 2.3 module will be required.\nOn UNIX, in order to check whether you have this module or not, you just need to run the following command in your terminal:\n\n```sh\n$ php -v | grep -oi 'xdebug'\n```\n\nIf `Xdebug` or equivalent gets displayed, then the module is properly installed.\n\n## A unit testing framework that can be made operational in 5 minutes!\n\n### Step 1: Install *atoum*\n\nYou just have to download [its PHAR archive](https://github.com/atoum/atoum/releases/download/3.2.0/atoum.phar) and store it where you wish, for example under `/path/to/project/tests/atoum.phar`.\nThis PHAR archive contains the latest development version to pass the totality of *atoum*'s unit tests.\n*atoum*'s source code is also available via [the GitHub repository](https://github.com/atoum/atoum).\nTo check if *atoum* works correctly with your configuration, you can execute all its unit tests.\nTo do that, you just need to run the following command in your terminal:\n\n```sh\n$ php atoum.phar --test-it\n```\n\n### Step 2: Write your tests\n\nUsing your preferred text editor, create the file `path/to/project/tests/units/helloWorld.php` and add the following code:\n\n```php\n\u003c?php\n\nnamespace vendor\\project\\tests\\units;\n\nrequire_once 'path/to/atoum.phar';\n\ninclude_once 'path/to/project/classes/helloWorld.php';\n\nuse atoum\\atoum;\nuse vendor\\project;\n\nclass helloWorld extends atoum\\test\n{\n    public function testSay()\n    {\n        $helloWorld = new project\\helloWorld();\n\n        $this-\u003estring($helloWorld-\u003esay())-\u003eisEqualTo('Hello World!');\n    }\n}\n```\n\n### Step 3: Run your test with the command line\n\nLaunch your terminal and run the following command:\n\n```sh\n$ php path/to/test/file[enter]\n```\n\nYou should get the following result or something equivalent:\n\n```sh\n\u003e atoum version XXX by Frédéric Hardy.\nError: Unattended exception: Tested class 'vendor\\project\\helloWorld' does not exist for test class 'vendor\\project\\tests\\units\\helloWorld'\n```\n\n### Step 4: Write the class corresponding to your test\n\nUsing again your preferred text editor, create the file `path/to/project/classes/helloWorld.php` and add the following code:\n\n```php\n\u003c?php\n\nnamespace vendor\\project;\n\nclass helloWorld\n{\n    public function say()\n    {\n        return 'Hello World!';\n    }\n}\n```\n\n### Step 5: Run your test once more\n\nIn the same terminal, run the following command once again:\n\n```sh\n$ php path/to/test/file[enter]\n```\n\nYou should get the following result, or something equivalent:\n\n```sh\n\u003e atoum version 288 by Frédéric Hardy.\n\u003e Run vendor\\project\\tests\\units\\helloWorld...\n[S___________________________________________________________][1/1]\n=\u003e Test duration: 0.00 second.\n=\u003e Memory usage: 0.25 Mb.\n\u003e Total test duration: 0.00 second.\n\u003e Total test memory usage: 0.25 Mb.\n\u003e Code coverage value: 100.00%\n\u003e Running duration: 0.08 second.\n\u003e Success (1 test, 1 method, 2 assertions, 0 error, 0 exception)!\n```\n\n### Step 6: Complete your tests and restart the cycle from Step 3\n\n```php\n\u003c?php\n\nnamespace vendor\\project\\tests\\units;\n\nrequire_once 'path/to/atoum.phar';\n\ninclude_once 'path/to/project/classes/helloWorld.php';\n\nuse atoum\\atoum;\nuse vendor\\project;\n\nclass helloWorld extends atoum\\test\n{\n    public function test__construct()\n    {\n        $helloWorld = new project\\helloWorld();\n\n        $this\n            -\u003estring($helloWorld-\u003esay())-\u003eisEqualTo('Hello!')\n            -\u003estring($helloWorld-\u003esay($name = 'Frédéric Hardy'))-\u003eisEqualTo('Hello ' . $name . '!')\n        ;\n    }\n}\n```\n\n## To go further\n\n[*atoum*'s documentation](http://docs.atoum.org) is still being written.\nAny help to improve it will be appreciated.\nHowever, if you want to further explore immediately *atoum*'s possibilities, we recommend:\n\n* Running in your terminal, either the command `php atoum.phar -h`, or the command `php scripts/runner.php -h`,\n* Exploring the contents of the `configurations` directory in *atoum*'s source, as it contains configuration file samples,\n* Exploring the contents of the `tests/unit/classes` directory in *atoum*'s source, as it contains all of the unit tests,\n* Read the (french) [conference slides](http://www.slideshare.net/impossiblium/atoum-le-framework-de-tests-unitaires-pour-php-53-simple-moderne-et-intuitif) about it, available online,\n* Read the (french) [wiki](https://github.com/atoum/atoum/wiki),\n* Join the [discussion channel](https://github.com/atoum/atoum/discussions),\n* Ask questions by e-mail at the address *support[AT]atoum(DOT)org*.\n\n## Troubleshooting\n\n### *atoum*'s PHAR archive seems to not be working\n\nIn this case, the first thing you will want to do is confirm whether you have the latest version of the archive.\nYou just need to [download](https://github.com/atoum/atoum/releases/download/2.6.0/atoum.phar) it again.\nIf it still doesn't work, run the following command in a terminal window:\n\n```sh\n$ php -n atoum.phar -v\n```\n\nIf you get *atoum*'s version number, then the problem is coming from your PHP configuration.\nIn 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.\nThe `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:\n\n```\nzend_extension = /path/to/ioncube_loader*.*\n```\n\nThe `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:\n\n```\nsuhosin.executor.include.whitelist=\"phar\"\n```\n\nFinally, 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.\nTo 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:\n\n```sh\n$ php -d detect_unicode=0 atoum.phar [options]\n```\n\nIf 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.\nYou can also ask for help from the *atoum* development staff on the [discussion channel](https://github.com/atoum/atoum/discussions) of the atoum repository..\n\n### Error: Constant `__COMPILER_HALT_OFFSET__` already defined `/path/to/atoum.phar`\n\nThis error comes from the fact the *atoum* PHAR archive is included in more than one place within your code using `include` or `require`.\nTo 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.\n\n### APC seems not work with *atoum*\n\n[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.\nWhen testing classes that use APC, you may get some failure message showing that `apc_fetch` function is unable to retrieve a value.\nAs all PHP extension, APC has some configuration options to enable it:\n\n* `apc.enabled` whether to enable or disable APC,\n* `apc.enable_cli`, whether to enable or disable APC for PHP CLI.\n\nIn 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*.\n\n### Getting segfault when mocking objects\n\nWhen using *atoum* and mocking objects, you will sometime get segfaults coming from [PHP](http://www.php.net).\nThese segfaults are caused by [XDebug](http://xdebug.org/) in version less than 2.1.0 which has problem handling reflection in some cases.\nTo check the current version of [XDebug](http://xdebug.org/), you can run `php -v`.\nTo fix this issue, you have to update [XDebug](http://xdebug.org/) to the latest [stable version](http://xdebug.org/download.php).\nIf you can't update [XDebug](http://xdebug.org/) on your system, you can still disable the extension to avoid getting segfaults.\nTo be sure that [XDebug](http://xdebug.org/) has been successfully updated or disabled, you can run `php -v`.\nWhen you are done updating or disabling [XDebug](http://xdebug.org/), run `php atoum.phar --test-it` to be sure that all the segfaults have gone and that *atoum* is working.\n\n---\n\n## Roadmap\n\nLooking for a roadmap?\n\n- [Here is](https://github.com/atoum/atoum/labels/In%20progress) the work in progress,\n- [And there](https://github.com/atoum/atoum/milestones/*) what will come in next releases.\n\n## Credits\n\natoum has been created by [Frédéric Hardy]. It is now led by a strong community of contributors. You can find them\nin the [committer list](https://github.com/atoum/atoum/graphs/contributors) or in the\n[Contributors team](https://github.com/orgs/atoum/teams/contributors).\n\n## License\n\natoum is released under the BSD-3-Clause License. See the bundled [LICENSE](LICENSE) file for details.\n\n[Frédéric Hardy]: https://github.com/mageekguy\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatoum%2Fatoum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatoum%2Fatoum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatoum%2Fatoum/lists"}