ScreenshotNeo

BlogHow-to

How to Capture Codeception Screenshots on Test Errors and Failures

Learn when Codeception captures failure screenshots, how to enable Recorder, save images manually, and diagnose missing artifacts.

By the ScreenshotNeo team30 September 20262 min read

How to Capture Codeception Screenshots on Test Errors and Failures

Short answer: Codeception documents an automatic screenshot for a failed acceptance test when the suite uses a browser module such as WebDriver. The image is shown in the HTML report. If you need the steps leading to the failure, enable the Recorder extension. If you use PhpBrowser, Codeception saves the last page artifact on failure; that is page content, not a browser screenshot.

Start by identifying the module in your acceptance suite. The capture method, output path, and whether you receive an image or page source all depend on that module.

1. Identify what Codeception will capture

Suite or feature Artifact Where to find it Best use
Acceptance with WebDriver Final screenshot for a failed test HTML report; output files are under the configured output directory See the last browser state
WebDriver Recorder Screenshot after each step plus an HTML slideshow tests/_output/record_*, including index.html Reconstruct the sequence before failure
WebDriver manual capture PNG screenshot tests/_output/debug by default for the public actor action Capture a known checkpoint
PhpBrowser Last shown page Configured output directory Inspect returned HTML and request state

Codeception’s Reporting documentation states that it saves a screenshot for a failed acceptance test and displays it in the HTML report. That statement is narrower than “every error always creates an image.” Setup errors, teardown errors, runner errors, and failures after the browser session has closed can follow different paths in your installed version.

2. Confirm the acceptance suite uses WebDriver

Open the suite file, commonly tests/Acceptance.suite.yml, and check the enabled modules. A typical browser suite looks like this:

actor: AcceptanceTester
modules:
  enabled:
    - WebDriver:
        url: https://example.test
        browser: chrome

The global codeception.yml file controls shared settings such as the output directory. The documented default is tests/_output. A suite file can override shared configuration, so inspect both files when an artifact is written somewhere unexpected.

paths:
  output: tests/_output

Run the failing test with the HTML report enabled by your project’s normal Codeception command. Open the generated report and check the failed test entry. If there is no image, continue with the checks in the troubleshooting section instead of assuming that the assertion type was unsupported.

3. Enable Recorder for every browser step

A final screenshot tells you where the test ended. Recorder shows how it got there: it captures after each step and creates a slideshow. It is intended for suites with WebDriver enabled.

Recorder preserves the sequence of browser states leading to a failed step.
Recorder preserves the sequence of browser states leading to a failed step.

Enable it globally in codeception.yml:

extensions:
  enabled:
    - Codeception\\Extension\\Recorder

You can also enable it in the acceptance suite configuration when only browser tests need recordings:

extensions:
  enabled:
    - Codeception\\Extension\\Recorder

The documented Recorder defaults include:

  • module: WebDriver
  • delete_successful: true, so recordings from passing tests are removed by default
  • delete_orphaned: false

Recordings are written to directories named tests/_output/record_*. Open the index.html file in a recording directory to view the slideshow. If you need recordings from successful tests for a short debugging run, set delete_successful: false, then restore the default to avoid filling the output directory.

extensions:
  enabled:
    - Codeception\\Extension\\Recorder:
        delete_successful: false
        delete_orphaned: true

Recorder also has options such as the module it observes and an error color for problems while generating a recording. Treat those as recording controls; they do not prove that every kind of test error will produce a screenshot.

4. Place a screenshot at a known point in a WebDriver test

Use the public actor action when you want a deliberate checkpoint:

<?php

$I->amOnPage('/account/edit');
$I->fillField('#email', 'dev@example.test');
$I->makeScreenshot('edit_page');
$I->click('Save');

The WebDriver module documentation places this image at:

tests/_output/debug/edit_page.png

Use a name that describes the state, not the assertion. Names such as checkout_before_submit and profile_validation_error make CI artifacts easier to find.

Saving to an explicit filename from a helper

WebDriver also documents the module method _saveScreenshot($filename). It is a hidden API, so keep it in helper or module code and verify it against the version installed in your project:

<?php

$webdriver = $this->getModule('WebDriver');
$webdriver->_saveScreenshot(codecept_output_dir() . 'screenshot_1.png');

The public makeScreenshot action is preferable in ordinary test code. The hidden method is useful when a helper already has a fully qualified destination.

5. Understand PhpBrowser’s different failure artifact

PhpBrowser uses HTTP requests through Guzzle/CURL rather than a real browser window. Its documentation says that, if a test fails, it stores the last shown page in the output directory. That means HTML or another page response, not a PNG image of rendered pixels.

Use PhpBrowser’s artifact to inspect response markup, redirects, and server output. Switch to WebDriver when you need CSS layout, JavaScript state, fonts, screenshots, or browser-only behavior.

6. Capture only when a test fails with a custom hook

For a custom module or helper, Codeception exposes the _failed($test, $fail) lifecycle hook before _after. A custom implementation can call WebDriver’s screenshot method from that hook, but it must account for the test lifecycle:

  • The browser session may never have started because setup failed.
  • The session may already be closed after a teardown failure.
  • Parallel workers need unique filenames and output directories.
  • A second exception while saving the image can hide the original failure.

Keep the hook defensive and log capture failures separately. The Codeception references establish the extension point and WebDriver save method, but they do not provide a universal implementation for every runner and teardown path.

7. A practical configuration checklist

  1. Identify the suite file and confirm whether it uses WebDriver or PhpBrowser.
  2. Check the global paths.output value and any suite-level override.
  3. Run one intentionally failing acceptance test and inspect the HTML report.
  4. Enable Recorder when the final state is not enough.
  5. Use makeScreenshot() for named checkpoints around risky interactions.
  6. Set delete_successful: false only during a bounded debugging run.
  7. Archive tests/_output as a CI artifact before the workspace is cleaned.
  8. Check the Codeception and module versions installed by CI; defaults can differ between releases.

8. Troubleshooting missing or unusable screenshots

Symptom Likely cause Fix
No screenshot in the report The test is not an acceptance test, the suite is not using WebDriver, or the failure occurred before a browser session existed. Confirm the suite and module, then use Recorder or an explicit makeScreenshot() checkpoint.
Only an HTML file appears The suite uses PhpBrowser. Read the saved page artifact, or migrate the scenario to WebDriver for a rendered image.
Recorder directory is missing The extension is not enabled in the active configuration, or the test passed and delete_successful removed it. Enable Recorder in the global or acceptance configuration and temporarily set delete_successful: false.
Recorder captures are incomplete A browser step failed before the next capture, the browser crashed, or the session ended. Inspect the last recorded step and browser logs; add a manual checkpoint before the fragile action.
Image is saved but cannot be found A suite-level output path overrides the global path, or CI runs from a different working directory. Print the resolved output path in CI and archive that directory explicitly.
Manual capture throws an exception The WebDriver session is not active, the browser process crashed, or the module version differs from the example. Capture after navigation has completed, verify the driver session, and check the installed WebDriver module API.
Screenshot shows a login page Authentication did not persist, cookies were lost, or the test was redirected. Assert the authenticated URL before the failing action and inspect cookies, redirects, and environment credentials.
Screenshot is blank or partly rendered The page was captured before JavaScript, fonts, or lazy content finished loading. Wait for a stable selector or an explicit condition before capturing; avoid arbitrary long sleeps when a state check is available.
CI cannot open the image The artifact was deleted during cleanup, the path is outside the archived directory, or the file permissions prevent collection. Archive tests/_output immediately after the test command and preserve failed-job artifacts.
Parallel jobs overwrite files Workers use the same screenshot name and directory. Include the worker ID, test name, and timestamp in custom filenames or isolate output per worker.

9. Performance, reliability, and storage

  • Default failure capture: captures only the final state, so it adds less work than recording every step.
  • Recorder: creates one image per step and an index page. Use it for a focused debugging run because image count and storage grow with test length.
  • Manual checkpoints: add predictable overhead only where you place them and keep CI artifacts easier to review.
  • Browser stability: screenshots depend on the browser session, display environment, page timing, and network. A missing image can be a symptom of an earlier browser failure.
  • Retention: archive failed-test output, then clean old recordings. Leaving successful recordings enabled indefinitely can consume workspace storage.
  • Reproducibility: record the Codeception version, module version, browser version, viewport, and CI worker when comparing screenshots.

10. Or skip the browser setup

If your goal is a clean screenshot of a URL rather than a screenshot tied to a Codeception browser session, ScreenshotNeo provides a single HTTP request. Its API accepts a URL and returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for the complete option list.

A screenshot API can clean common overlays before returning the captured page.
A screenshot API can clean common overlays before returning the captured page.

cURL

curl -G 'https://api.screenshotneo.com/v1/shot' \
  -d access_key=YOUR_API_KEY \
  --data-urlencode 'url=https://stripe.com' \
  -o shot.webp

Python

import requests

r = requests.get(
    'https://api.screenshotneo.com/v1/shot',
    params={
        'access_key': 'YOUR_API_KEY',
        'url': 'https://stripe.com',
    },
    timeout=90,
)
r.raise_for_status()
with open('shot.webp', 'wb') as f:
    f.write(r.content)

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
});

const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const file = Buffer.from(await res.arrayBuffer());
await require('node:fs').promises.writeFile('shot.webp', file);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the result with X-Page-Verdict and X-Billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. You can also use full-page capture, CSS element selection, device presets, custom headers and cookies, waits, blocking rules, custom CSS or JavaScript, caching, signed links, asynchronous jobs, bulk capture, and PDF options.

There is a free plan with 1,000 screenshots per month and no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account.

11. FAQ

Does Codeception take a screenshot for every error?

The documented default is for a failed acceptance test. It does not promise an image for every setup, teardown, runner, or browser-process error.

What is the difference between a failure screenshot and Recorder?

The failure screenshot represents the final browser state. Recorder captures each step and creates a slideshow so you can trace the state changes.

Why do I get HTML instead of PNG?

You are likely using PhpBrowser, which saves the last shown page rather than a rendered browser image.

Where does Codeception write output?

The documented global default is tests/_output, but suite configuration can override it.

Should I use the hidden _saveScreenshot() method?

Use the public actor action in tests. Reserve _saveScreenshot() for helpers or custom modules and verify it against your installed WebDriver version.