Codeception is a full-stack PHP testing framework

Codeception brings BDD-style testing to PHP

Codeception is a modern full-stack testing framework for PHP. Its tagline is "Modern PHP Testing for everyone." Inspired by behavior-driven development, it offers a new way to write acceptance, functional, and even unit tests. Instead of asserting against internals, tests describe what is being tested and how, using PHP so descriptions stay readable. After a run, Codeception shows the actions taken and the results observed, which keeps test output close to the scenario being checked. This scenario first style is what sets it apart from older xUnit style PHP test runners. The README invites users to describe what they test and how they test it, using PHP to write those descriptions faster, then run tests to see the actions taken and the results seen.

A sample acceptance test reads like a scenario

The README's sample test shows the style. A test actor named `$I` navigates a page, clicks links, submits a form, and checks the outcome. The lines read as steps: open the home page, click Pages, click New, confirm a New Page appears, submit a form, and verify the database holds the new record. This scenario style is the core of Codeception's acceptance and functional suites, and it keeps test intent visible to non-developers on the team. Each helper method maps to a user or system action, so the test doubles as living documentation of the feature's expected flow. The final check on the database confirms the form write persisted, closing the loop between the UI step and the stored record.

$I->amOnPage('/');
$I->click('Pages');
$I->click('New');
$I->see('New Page');
$I->submitForm('form#new_page', ['title' => 'Movie Review']);
$I->see('page created'); // notice generated
$I->see('Movie Review','h1'); // head of page of is our title
$I->seeInCurrentUrl('pages/movie-review'); // slug is generated
$I->seeInDatabase('pages', ['title' => 'Movie Review']); // data is stored in database

Installing through Composer or a Phar

The recommended install is Composer: `composer require "codeception/codeception" --dev`. A self-contained Phar is also available from codeception.com; you download `codecept.phar`, make it executable, and move it into your PATH so you can call `codecept` directly. Once placed, commands such as `codecept bootstrap` and `codecept run` work from the command line. The Phar route is handy on systems where Composer is not set up, since it bundles the runner in one file.

composer require "codeception/codeception" --dev

codecept bootstrap

Bootstrapping a project and running tests

After installation, `codecept bootstrap` creates a default directory structure and default test suites. From there you write suites for acceptance, functional, and unit work. The README points to the online documentation and QuickStart for deeper guidance. Because the bootstrap lays out suites and config, new projects get a working test layout without manual folder setup. A first run then exercises the generated skeleton so the team can confirm the toolchain before adding real cases. The default suites produced by bootstrap correspond to the acceptance, functional, and unit levels, so a team can grow coverage in each lane. The generated config points modules at the right application layers, which avoids wiring that by hand on every new project.

Unit testing with PHPUnit inside Codeception

For unit testing you can keep classic PHPUnit tests, because Codeception can run them too. This lets teams adopt Codeception for acceptance and functional coverage while leaving existing PHPUnit classes in place. The framework therefore acts as a single runner across test types rather than a replacement for PHPUnit. PHPUnit remains the engine for unit-level assertions, and Codeception wraps it so all suites run from one command. The README states this directly, noting that classic PHPUnit tests can stay as they are. Mixing PHPUnit with Codeception suites means a legacy test folder can move over without a rewrite, lowering the cost of adoption. The shared runner also produces one report across all levels, which is easier to read in continuous integration than several separate outputs.

License and contribution model

Codeception is released under the MIT license. The project welcomes community contributions to both code and documentation, with a contributing guide referenced for additions and fixes. The README also carries a "Stand With Ukraine" banner, reflecting the project's stated position. Documentation sources are hosted alongside the site, so readers can propose doc changes through the same repository workflow as code. This open model keeps the framework and its docs in one contribution stream. Because the docs live in the same contribution workflow, a documentation fix from a user can ship in the same pull request as the code it describes. The MIT license keeps the framework usable in closed source PHP products without a separate commercial agreement.

Editorial conclusion

Codeception is a modern full-stack testing framework for PHP that brings a behavior-driven, scenario style to acceptance, functional, and unit tests. Its sample tests read as clear steps performed by a test actor, which keeps intent visible to the whole team, and it installs through Composer or a single Phar file. After a quick bootstrap that lays out suites and config, the same runner can execute classic PHPUnit tests as well, so teams consolidate their test commands. Released under the MIT license with an open contribution model, Codeception fits projects that want readable PHP tests across the stack without abandoning the PHPUnit classes they already maintain.

Frequently asked questions

Official sources

1. Codeception/Codeception on GitHub
2. License: MIT
3. Project website
4. README
5. Releases