Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Yes—Codeception documents an automatic screenshot for a failed acceptance test. The image is shown in the HTML report. What you get depends on the suite and module: WebDriver can capture browser images (automatically, per step with Recorder, or manually), while PhpBrowser saves the last page artifact rather than a browser screenshot. The exact behavior for setup, teardown, runner, and other error paths should be checked against your installed Codeception and module versions.
What Codeception captures by default
Codeception’s Reporting documentation says: “By default Codeception saves the screenshot for a failed test for acceptance tests and show it in HTML report.” This documented default is specifically for failed acceptance tests. It should not be broadened into a guarantee that every assertion failure, uncaught exception, setup error, teardown error, or runner-level error creates an image.
First identify the module used by the suite. A browser-driven acceptance suite normally uses WebDriver; an HTTP-level suite may use PhpBrowser. Their failure artifacts are different:
| Suite/module | Artifact | Typical location or view | Best use |
|---|---|---|---|
| Acceptance with WebDriver | Final browser screenshot for a failed test | HTML report; files are under the configured output directory | See the state at failure |
| WebDriver plus Recorder | Screenshot after each test step and an HTML slideshow | tests/_output/record_*, including index.html |
Reconstruct the sequence before failure |
| WebDriver manual capture | PNG created by an explicit action | tests/_output/debug/<name>.png by default |
Capture a known checkpoint |
| PhpBrowser | Last shown page, not a browser image | Output directory on failure | Inspect returned HTML or page content |
The global paths.output default is tests/_output. A suite file such as Acceptance.suite.yml can configure modules and override shared settings from codeception.yml.
#1 Best Overall
Find the output directory and report
- Run the acceptance suite in the normal way, for example
vendor/bin/codecept run acceptance --htmlif your project uses the HTML report option. - Open the generated HTML report and select the failed test. The documented default screenshot is embedded or linked there.
- Inspect
tests/_output(or the directory set bypaths.output) when you need the underlying files. - Confirm the installed Codeception version and the WebDriver or PhpBrowser module version before relying on a default. The current documentation and older 4.x guidance are not evidence that every release behaves identically.
Record every WebDriver step with Recorder
A single final image can miss the interaction that caused the failure. Recorder takes a screenshot after each step and presents the images as a slideshow. It requires a suite with WebDriver enabled.
Enable the extension
Add the extension to codeception.yml or to the acceptance suite configuration:
extensions:
enabled:
- Codeception\Extension\RecorderThe documented defaults include module: WebDriver, delete_successful: true, and delete_orphaned: false. Recordings are written to directories named tests/_output/record_*, with an index.html slideshow. Because delete_successful defaults to true, recordings for passing tests are removed unless you change that option.
Free tools Windows power users keep installed
One-click scans. No signup required.
Useful Recorder considerations
- Use Recorder when timing and sequence matter, not just the final DOM state.
- Keep the default cleanup if recordings are only needed for failures; disable it when you are diagnosing successful flows or building a visual audit trail.
- Recorder’s
error_colorconcerns a problem while generating a recording; it does not prove that every kind of Codeception error automatically produces a screenshot. - Large suites can create many image files. Set retention deliberately and archive only the failing test’s directory when sharing diagnostics.
Take a screenshot at a chosen point
For ordinary WebDriver test code, use the public actor action:
$I->makeScreenshot('edit_page');
// tests/_output/debug/edit_page.pngThe name is used for the image filename. Place captures immediately before and after a risky interaction when you need a visual comparison. The browser session must still be available when the action runs; a crash or an early session-creation failure leaves no page to capture.
Saving to an explicit filename in helper code
WebDriver documents a hidden API that saves the current page to a supplied path:
$this->getModule('WebDriver')->_saveScreenshot(codecept_output_dir() . 'screenshot_1.png');This is an implementation detail for a helper or module, not the preferred call in a normal test. Verify it against the installed module version, and ensure the destination directory exists and is writable.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →PhpBrowser: a page artifact, not a screenshot
PhpBrowser uses Guzzle/CURL rather than a real browser. Its module documentation states: “If test fails stores last shown page in ‘output’ dir.” Treat that file as the last response/page source. It will not contain pixels, layout, JavaScript-rendered state, or browser chrome. If your debugging question is “what did the user see?”, use WebDriver; if it is “what HTML did the HTTP client receive?”, PhpBrowser’s failure artifact may be sufficient.
Configuration scope and practical setup
Global configuration
Use codeception.yml for shared settings such as the output path and extensions that should apply broadly. The default output path is tests/_output.
Acceptance-suite configuration
Use Acceptance.suite.yml for acceptance-specific modules and options. Suite configuration can override shared configuration. Recorder may be enabled globally or in the acceptance suite, but keeping it acceptance-only avoids recording non-browser suites.
Verify the browser layer
- Confirm the acceptance suite actually lists WebDriver and that its browser/URL settings are valid.
- Run one deliberately failing test and inspect both the report and output directory.
- Check filesystem permissions for
tests/_outputand any custom directory. - When running in CI, publish the output directory and HTML report as build artifacts; otherwise the files may disappear with the workspace.
Failure paths that need qualification
The phrase “on test errors” covers several lifecycle points. The documented default is phrased as a “failed test,” not as every possible error. A failure after the browser has loaded is the most likely case for a useful image. A WebDriver startup failure, a browser crash, a setup exception before a session exists, or a teardown error may provide no screenshot. Test these paths in your version rather than assuming they are covered.
Custom failure handling
Codeception’s module reference lists _failed($test, $fail) as a hook invoked when a test fails before _after. Combined with WebDriver’s documented _saveScreenshot, this gives a possible extension point for a custom module or helper. It is not a complete universal implementation: browser-session availability, teardown order, and runner behavior determine whether a capture is possible.
Rank #3
Troubleshooting missing or misleading captures
No image appears in the HTML report
Check that the test is in an acceptance suite, that the report was generated for the same run, and that the WebDriver session reached the page. Then inspect the configured output directory and CI artifact settings.
Recorder creates no slideshow
Confirm the extension is enabled under the exact configuration file used by the run and that the suite has WebDriver. Look for record_* directories and an index.html; a different output path can make them appear missing.
Only successful recordings are missing
This is the documented default: delete_successful: true. Set it to false when you need recordings from passing tests.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsThe saved file is HTML, not PNG
You are probably using PhpBrowser. Its documented failure artifact is the last shown page. Switch the acceptance flow to WebDriver for a visual screenshot.
Manual capture fails with a path error
Use a relative name with makeScreenshot, or create the directory before calling the hidden API. Ensure the process can write to tests/_output/debug or your custom destination.
There is no screenshot after a startup error
No browser page may have existed. Capture an earlier diagnostic (such as WebDriver logs), fix the driver/browser configuration, and do not treat the absence of an image as proof that Codeception ignored a normal failed test.
Rank #4
- Used Book in Good Condition
Performance, reliability, and retention
- Final failure screenshots add little overhead because they are taken only when needed; Recorder adds an image operation after every step and can increase runtime and storage substantially.
- Use Recorder selectively on a diagnostic job or tagged suite. Keep ordinary CI runs on the default failure capture unless sequence evidence is required.
- Choose a retention policy for
tests/_output. In CI, upload only failed-test directories when artifact volume matters. - Redact credentials and personal data before sharing screenshots or HTML reports. Custom headers, cookies, and authenticated pages can expose sensitive content.
Or skip the browser setup
If you need a standalone capture of a URL rather than a Codeception test artifact, ScreenshotNeo provides a one-request screenshot API and an MCP server for AI agents. The cURL example is:
Recommended Free Tools
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for all options. Before capture, it accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP tools—take_screenshot, get_page_info, and capture_pdf—work with Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Python and Node.js alternatives for the same API call
Python
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").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}`);Frequently Asked Questions
Does Codeception take screenshots for unit tests?
The documented automatic screenshot behavior is for failed acceptance tests. Do not assume unit or non-browser suites produce an image.
Can Recorder show what happened before the failing assertion?
Yes. With WebDriver enabled, Recorder captures after each step and creates a slideshow in a record_* output directory.
Why is my PhpBrowser output not an image?
PhpBrowser saves the last shown page on failure. It is an HTML/page artifact from an HTTP client, not a browser-rendered screenshot.
Where should CI upload Codeception captures?
Publish the configured output directory, normally tests/_output, together with the generated HTML report so the files remain available after the build workspace is deleted.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
