Introduction
Codeception is a modern full-stack testing framework for PHP applications. It provides an elegant and powerful approach to testing web applications by combining acceptance, functional, and unit testing capabilities into a single, cohesive framework.
This documentation covers the implementation and usage of Codeception within our project environment, including custom enhancements and specific configuration approaches we've developed.
What is Codeception?
Codeception is built on top of PHPUnit and integrates Symfony components to provide a comprehensive testing solution. It allows you to write tests in a human-readable format while maintaining the power and flexibility needed for complex testing scenarios.
The framework supports three main types of tests:
Acceptance Tests - Test your application from the user's perspective through a web browser. These tests interact with your application exactly as a real user would, clicking buttons, filling forms, and verifying the results. Acceptance tests can execute JavaScript, making them suitable for testing modern interactive web applications with dynamic content and AJAX requests. However, they are the slowest type of tests due to the overhead of browser automation.
Functional Tests - Test your application at the framework level without going through the actual HTTP layer. These tests are significantly faster than acceptance tests while still testing the application's behavior through the full stack. They cannot execute JavaScript, so they're best suited for testing server-side logic and standard request-response cycles.
Unit Tests - Test individual classes and methods in isolation. These are the fastest tests and focus on verifying that small units of code work correctly. They run entirely in PHP without any framework or browser overhead.
Our Implementation
In our projects, we use Codeception with several custom enhancements to streamline the testing process and improve developer experience.
Docker-Based Testing Environment
All tests run within a Docker Compose environment, ensuring consistency across different development machines and eliminating "works on my machine" issues. The containerized approach includes:
- Pre-configured PHP environment with all necessary extensions
- Selenium containers for browser automation in acceptance tests
- Isolated database instances for testing
- Network configuration that mirrors production architecture
Custom Codeception Plugin
We've developed a custom Codeception plugin called czechgroup/codeception-base that extends the framework's capabilities. This plugin is distributed through our private Satis repository at satis.czechgroup.cz.
The plugin includes enhanced dependency injection capabilities through a custom DI module, making it easier to load and configure modules during test execution. This simplification reduces boilerplate code and makes test setup more intuitive.
For detailed instructions on accessing our Satis repository and configuring Composer authentication, see the article Setting Up Access to CzechGroup Satis Repository.
Testing Workflow
Tests are executed through Docker Compose commands, which handle all the infrastructure setup automatically. The testing workflow typically involves:
- Starting the Docker Compose environment
- Running the appropriate Codeception command for your test suite
- Reviewing test results and debugging any failures
- Shutting down the environment when testing is complete
This approach ensures that every test run starts from a clean, known state, reducing flaky tests and improving reliability.
Documentation Structure
This wiki provides comprehensive guidance on working with Codeception in our environment. The documentation is organized into several key areas:
- Project Structure - Understanding how test projects are organized
- Suite Configuration - Setting up and configuring different test suites
- Writing Tests - Best practices and patterns for writing effective tests
- Command Execution - Running tests and understanding the various options
- Custom Modules - Leveraging our custom enhancements
Each section builds upon the previous ones, so we recommend reading through the documentation sequentially if you're new to our testing setup.
Getting Started
Before diving into writing tests, it's important to understand the overall structure and philosophy of our testing approach. The following articles in this wiki will guide you through setting up your first test project, understanding the configuration options, and writing your first tests.
Whether you're new to Codeception or experienced with the framework, our custom implementation includes several enhancements and conventions that will help you write better tests more efficiently.