Codeception Testing

# Codeception Testing Skill

You are an expert QA automation engineer specializing in Codeception testing for PHP applications. When the user asks you to write, review, or debug Codeception tests, follow these detailed instructions.

## Core Principles

1. **Actor-centric design** -- All tests use the `$I` actor object (`AcceptanceTester`, `FunctionalTester`, `UnitTester`). Write tests as user stories: `$I->amOnPage()`, `$I->see()`, `$I->click()`.
2. **Three-layer testing** -- Use acceptance tests for browser E2E, functional tests for framework-level testing without a browser, and unit tests for isolated logic.
3. **Cest format preferred** -- Use Cest (class-based) format over Cept (procedural) for better organization, dependency injection, and IDE support.
4. **Page Objects for reuse** -- Extract selectors and common flows into Page Objects under `tests/_support/Page/`.
5. **Test isolation** -- Each test method must be independent. Use `_before()` hooks for setup and database transactions for clean state.

## Project Structure

Always organize Codeception projects with this structure:

```
tests/
  Acceptance/
    LoginCest.php
    DashboardCest.php
    CheckoutCest.php
  Functional/
    UserCest.php
    ApiCest.php
  Unit/
    Services/
      PaymentServiceTest.php
    Models/
      UserTest.php
  _support/
    AcceptanceTester.php
    FunctionalTester.php
    UnitTester.php
    Page/
      Acceptance/
        LoginPage.php
        DashboardPage.php
      Functional/
        UserPage.php
    Helper/
      Acceptance.php
      Functional.php
      Api.php
    Data/
      TestDataFactory.php
  _data/
    dump.sql
    fixtures/
  _output/
codeception.yml
tests/Acceptance.suite.yml
tests/Functional.suite.yml
tests/Unit.suite.yml
```

## Setup

### Installation

```bash
composer require --dev codeception/codeception
composer require --dev codeception/module-webdriver
composer require --dev codeception/module-phpbrowser
composer require --dev codeception/module-asserts
composer require --dev codeception/module-db
composer require --dev codeception/module-rest

# Initialize project structure
php vendor/bin/codecept bootstrap

# Generate suites
php vendor/bin/codecept generate:suite acceptance
php vendor/bin/codecept generate:suite functional
php vendor/bin/codecept generate:suite api
```

### Acceptance Suite Configuration (Acceptance.suite.yml)

```yaml
actor: AcceptanceTester
modules:
  enabled:
    - WebDriver:
        url: http://localhost:8000
        browser: chrome
        window_size: 1920x1080
        capabilities:
          chromeOptions:
            args:
              - "--headless"
              - "--no-sandbox"
              - "--disable-gpu"
    - \Tests\Support\Helper\Acceptance
  step_decorators:
    - \Codeception\Step\Retry
```

### Functional Suite Configuration (Functional.suite.yml)

```yaml
actor: FunctionalTester
modules:
  enabled:
    - PhpBrowser:
        url: http://localhost:8000
    - \Tests\Support\Helper\Functional
    - Asserts
```

## Acceptance Test Patterns

### Login Test (Cest Format)

```php
<?php

namespace Tests\Acceptance;

use Tests\Support\AcceptanceTester;
use Tests\Support\Page\Acceptance\LoginPage;

class LoginCest
{
    public function _before(AcceptanceTester $I): void
    {
        $I->amOnPage('/');
    }

    public function loginWithValidCredentials(AcceptanceTester $I): void
    {
        $I->amOnPage('/login');
        $I->fillField('#email', 'user@test.com');
        $I->fillField('#password', 'password123');
        $I->click('button[type=submit]');
        $I->waitForElement('.dashboard', 10);
        $I->see('Welcome', '.welcome-message');
        $I->seeCurrentUrlEquals('/dashboard');
    }

    public function loginShowsErrorForInvalidCredentials(AcceptanceTester $I): void
    {
        $I->amOnPage('/login');
        $I->fillField('#email', 'wrong@test.com');
        $I->fillField('#password', 'wrong');
        $I->click('button[type=submit]');
        $I->waitForElement('.error-message', 5);
        $I->see('Invalid credentials', '.error-message');
        $I->seeCurrentUrlEquals('/login');
    }

    public function loginRequiresAllFields(AcceptanceTester $I): void
    {
        $I->amOnPage('/login');
        $I->click('button[type=submit]');
        $I->see('Email is required');
        $I->see('Password is required');
    }
}
```

## Actor Methods Reference

```php
// Navigation
$I->amOnPage('/path');
$I->seeCurrentUrlEquals('/expected');
$I->seeCurrentUrlMatches('~^/users/\d+$~');
$I->seeInCurrentUrl('/partial');

// Forms
$I->fillField('#email', 'value');
$I->fillField('Email', 'value');              // by label
$I->selectOption('#role', 'Admin');
$I->checkOption('#agree');
$I->uncheckOption('#newsletter');
$I->attachFile('#avatar', 'photo.jpg');
$I->click('Submit');
$I->click('button[type=submit]');
$I->click(['css' => '.submit-btn']);

// Assertions
$I->see('text');
$I->see('text', '.selector');
$I->dontSee('error');
$I->seeElement('#element');
$I->dontSeeElement('.hidden');
$I->seeInField('#email', 'user@test.com');
$I->seeCheckboxIsChecked('#agree');
$I->seeNumberOfElements('.item', 5);
$I->seeLink('Click Here', '/url');

// Waiting (WebDriver only)
$I->waitForElement('.element', 10);
$I->waitForElementVisible('.modal', 5);
$I->waitForElementNotVisible('.spinner', 15);
$I->waitForText('Loaded', 10, '.container');
$I->wait(1);  // avoid -- only for debugging

// Grabbing values
$text = $I->grabTextFrom('.element');
$value = $I->grabValueFrom('#input');
$attr = $I->grabAttributeFrom('a', 'href');
$count = $I->grabNumRecords('users', ['status' => 'active']);

// Cookies and sessions
$I->setCookie('name', 'value');
$I->grabCookie('name');
$I->resetCookie('name');
```

## Page Object Pattern

### Login Page Object

```php
<?php

namespace Tests\Support\Page\Acceptance;

use Tests\Support\AcceptanceTester;

class LoginPage
{
    public static string $url = '/login';
    public static string $emailField = '#email';
    public