File: /home/labeautef/labeautedegaby.com/wp-content/plugins/imagify/docs/E2E_TESTING.md
# Imagify — End-to-End Testing
This document is the canonical reference for the Imagify Playwright E2E test suite. **Read this before writing any new tests.**
---
## Architecture overview
| Layer | Path | Purpose |
|-------|------|---------|
| Config | `Tests/e2e/playwright.config.ts` | Playwright base config (baseURL, reporters, timeouts) |
| Fixtures | `Tests/e2e/fixtures/` | Shared helpers: login, WP-CLI wrapper, API key guard |
| Page objects | `Tests/e2e/pages/` | One class per major admin surface |
| Specs | `Tests/e2e/specs/` | Test files, one per feature area |
| Dev scripts | `bin/dev-up.sh`, `bin/dev-down.sh`, `bin/dev-seed.sh` | Local environment lifecycle |
| CI | `.github/workflows/e2e.yml` | Automated runs on pull requests |
All tests run against a local WordPress environment managed by `@wordpress/env` (Docker). The environment maps the plugin root directly into the container at `wp-content/plugins/imagify`.
---
## Admin URLs
| Surface | URL |
|---------|-----|
| Settings | `/wp-admin/options-general.php?page=imagify` |
| Bulk optimization | `/wp-admin/upload.php?page=imagify-bulk-optimization` |
| Custom folders | `/wp-admin/upload.php?page=imagify-files` |
| Media library (list) | `/wp-admin/upload.php?mode=list` |
| Plugins list | `/wp-admin/plugins.php` |
---
## Running tests locally
### One-time setup
```bash
# From the repository root
bash bin/dev-up.sh # Start wp-env + activate plugin + seed test data
cd Tests/e2e
npm install
npx playwright install chromium
```
### Running
```bash
cd Tests/e2e
npm test # Headless, list reporter
npm run test:headed # With browser UI visible
npm run test:ui # Playwright interactive UI mode
npm run report # Open the last HTML report
```
### Environment variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `IMAGIFY_BASE_URL` | `http://localhost:8888` | Override the WordPress base URL |
| `IMAGIFY_ADMIN_USER` | `admin` | WP admin username |
| `IMAGIFY_ADMIN_PASS` | `password` | WP admin password |
| `IMAGIFY_TESTS_API_KEY` | _(unset)_ | Real Imagify API key — required for optimization tests |
Set `IMAGIFY_TESTS_API_KEY` to run tests that call the Imagify API. Without it, those tests are automatically skipped.
---
## Page objects
Each major admin surface has a Page Object class. Use them instead of raw selectors — they centralize selector maintenance.
### `SettingsPage` (`Tests/e2e/pages/settings.ts`)
```typescript
import { SettingsPage } from '../pages/settings';
const settings = new SettingsPage( page );
await settings.goto();
await settings.setApiKey( process.env.IMAGIFY_TESTS_API_KEY! );
```
Key members: `apiKeyInput`, `saveButton`, `successNotice`, `goto()`, `setApiKey()`, `getApiKey()`, `expectNoFatalError()`.
### `BulkOptimizationPage` (`Tests/e2e/pages/bulk-optimization.ts`)
```typescript
import { BulkOptimizationPage } from '../pages/bulk-optimization';
const bulk = new BulkOptimizationPage( page );
await bulk.goto();
await expect( bulk.optimizeButton ).toBeVisible();
```
Key members: `optimizeButton`, `progressBar`, `statsTable`, `goto()`, `expectNoFatalError()`.
### `MediaLibraryPage` (`Tests/e2e/pages/media-library.ts`)
```typescript
import { MediaLibraryPage } from '../pages/media-library';
const library = new MediaLibraryPage( page );
await library.goto();
await expect( library.imagifyColumn ).toBeVisible();
```
Key members: `imagifyColumn`, `goto()`, `hasImagifyColumn()`, `getFirstAttachmentStatus()`, `expectNoFatalError()`.
---
## Fixtures
### `loginAsAdmin( page )` — `Tests/e2e/fixtures/auth.ts`
Logs in as the WordPress administrator. Idempotent: skips the login form if a session cookie is already active.
```typescript
import { loginAsAdmin } from '../fixtures/auth';
test.beforeEach( async ( { page } ) => {
await loginAsAdmin( page );
} );
```
### `wpCli( command )` — `Tests/e2e/fixtures/wp-cli.ts`
Runs a WP-CLI command inside the wp-env `cli` container. Returns stdout as a string.
```typescript
import { wpCli } from '../fixtures/wp-cli';
const value = wpCli( 'option get imagify_settings --format=json' );
```
### `hasApiKey()` — `Tests/e2e/fixtures/wp-cli.ts`
Returns `true` if `IMAGIFY_TESTS_API_KEY` is set. Use with `test.skip` to gate API-dependent tests:
```typescript
import { hasApiKey } from '../fixtures/wp-cli';
test.skip( ! hasApiKey(), 'IMAGIFY_TESTS_API_KEY not set' );
```
---
## Writing new tests
### Determinism rules
- **Never** use `setTimeout` or `waitForTimeout`. Use web-first assertions (`toBeVisible`, `toHaveValue`, `toHaveURL`, etc.) which have built-in retry.
- **Never** assert on volatile values (timestamps, auto-increment IDs) without normalization.
- **Always** seed state before tests that depend on specific DB content.
### API key guard
Any test that triggers image optimization through the Imagify API must be guarded:
```typescript
test( 'Optimizing an image succeeds', async ( { page } ) => {
test.skip( ! process.env.IMAGIFY_TESTS_API_KEY, 'IMAGIFY_TESTS_API_KEY not set — skipping live optimization test' );
// ... test body
} );
```
### Adding a new page object
Create `Tests/e2e/pages/<feature>.ts`:
```typescript
import { Page, Locator, expect } from '@playwright/test';
export class FeaturePage {
readonly page: Page;
// locators...
constructor( page: Page ) {
this.page = page;
// initialize locators
}
async goto(): Promise<void> {
await this.page.goto( '/wp-admin/...' );
await this.page.waitForLoadState( 'networkidle' );
}
async expectNoFatalError(): Promise<void> {
await expect( this.page.locator( '.wp-die-message, #error-page' ) ).toHaveCount( 0 );
}
}
```
### Adding a new spec
Create `Tests/e2e/specs/<feature>.spec.ts`. Follow this template:
```typescript
import { test, expect } from '@playwright/test';
import { loginAsAdmin } from '../fixtures/auth';
import { FeaturePage } from '../pages/<feature>';
test.describe( 'Feature area', () => {
test.beforeEach( async ( { page } ) => {
await loginAsAdmin( page );
} );
test( 'Something works', async ( { page } ) => {
const featurePage = new FeaturePage( page );
await featurePage.goto();
await featurePage.expectNoFatalError();
// assertions...
} );
} );
```
---
## CI
The E2E workflow (`.github/workflows/e2e.yml`) runs on pull requests that touch:
- `classes/**`, `inc/**`, `assets/**`, `views/**` — PHP/JS plugin code
- `Tests/e2e/**` — test files themselves
- `.wp-env.json`, `bin/dev-up.sh`, `bin/dev-seed.sh` — environment config
- `composer.json`, `.github/workflows/e2e.yml`
The `IMAGIFY_TESTS_API_KEY` secret must be set in the GitHub repository settings for API-dependent tests to run. Without it, those tests are automatically skipped and the suite still passes.
---
## Known coverage gaps
The following areas are not yet covered by automated E2E tests (good places to contribute):
- Custom folders optimization workflow
- WP-CLI bulk-optimize and bulk-restore commands (use `wpCli()` fixture)
- Admin notices (API quota reached, outdated plugin)
- Network mode (proxy URL, login/password settings)
- Multisite network activation