Use the Cypress 10-and-later setup for cypress-mochawesome-reporter, then enable embeddedScreenshots: true. Add inlineAssets: true when the report must be one portable HTML file. Cypress creates screenshots explicitly with cy.screenshot() and automatically after failures (unless that behavior is disabled). The reporter associates those files with the test result and can embed their bytes in the generated Mochawesome HTML.
What the two reporter options actually do
Screenshot attachment, image embedding, and a self-contained report are different outcomes:
- Attachment: the report references a screenshot file associated with a test.
embeddedScreenshots: converts external screenshot files to base64 data and places them in the HTML.inlineAssets: inlines report assets so the deliverable can be opened as a single HTML file without a neighboring assets directory.
Both options are documented by the reporter project. Check its compatibility table before selecting a release: Cypress and Node requirements vary by reporter version, and the current v5 line has different requirements from older releases.
Prerequisites and version check
- Cypress 10 or later, using the reporter project’s Cypress >=10 setup.
- A Node.js version supported by the reporter release you install.
- An npm project in which Cypress already runs.
- A CI artifact policy if screenshots or reports must be downloaded from a build.
cypress-mochawesome-reporter is a community extension listed in Cypress’s plugin directory, not an official Cypress product. Use the release’s README and compatibility table at the project repository as the authority for your installed Cypress and Node versions.
Recommended Cypress 10 setup
1. Install the reporter
Install it as a development dependency with the package manager used by your project:
npm install cypress-mochawesome-reporter --save-devDo not copy a Cypress 9 plugin file into a Cypress 10 project. Cypress 10 moved configuration and Node-event wiring; follow the Cypress >=10 tutorial in the reporter README for the release you installed.
2. Configure the reporter and Node events
In cypress.config.js (or the TypeScript equivalent), set the reporter and add the reporter’s documented event setup. A representative configuration is:
const { defineConfig } = require('cypress');
module.exports = defineConfig({
reporter: 'cypress-mochawesome-reporter',
reporterOptions: {
embeddedScreenshots: true,
inlineAssets: true
},
e2e: {
setupNodeEvents(on, config) {
require('cypress-mochawesome-reporter/plugin')(on);
return config;
}
}
});The exact import or event-registration form can differ between reporter releases and JavaScript/TypeScript projects. Copy the matching form from the README rather than mixing examples from different major versions. The two reporter options are the important part for image embedding.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →3. Choose how Cypress captures images
Add an explicit screenshot where a visual checkpoint matters:
describe('checkout', () => {
it('shows the confirmation page', () => {
cy.visit('/checkout');
cy.get('[data-testid="pay-now"]').click();
cy.get('[data-testid="confirmation"]').should('be.visible');
cy.screenshot('checkout-confirmation');
});
});Cypress also takes a screenshot automatically when a test fails during a run, unless screenshot-on-failure behavior has been disabled. Screenshots are written to the configured screenshotsFolder; the default is cypress/screenshots. You can make that location explicit:
module.exports = defineConfig({
screenshotsFolder: 'cypress/screenshots',
reporter: 'cypress-mochawesome-reporter',
reporterOptions: {
embeddedScreenshots: true,
inlineAssets: true
}
});Keep screenshot names stable and meaningful. Cypress may create subdirectories based on the spec and test title, so avoid assuming every image is directly under the folder root.
4. Run the suite and locate the HTML
Run Cypress in headless mode using the browser and spec selection appropriate for your project:
Recommended Free Tools
npx cypress runThe reporter generates its HTML output according to its documented defaults and options. Open the generated file in a browser and inspect a test that has an explicit or failure screenshot. With both options enabled, the HTML should open with its images even when copied without the report’s asset directory.
Single file versus a report directory
| Requirement | Configuration | Result |
|---|---|---|
| Show screenshots in the report while keeping external files | embeddedScreenshots: false (or omit it) |
Images remain separate assets referenced by the report. |
| Put screenshot bytes in the HTML | embeddedScreenshots: true |
Screenshot data is embedded as base64 in the report. |
| Deliver one portable HTML file | embeddedScreenshots: true and inlineAssets: true |
Images and report assets are inlined as documented by the reporter. |
A standalone file is convenient for email, issue attachments, and long-term archiving, but it can be substantially larger than a report that references image files. For CI interfaces, retaining the report directory as an artifact can be preferable when download size matters.
CI artifacts and retention
Cypress documents exporting screenshots and videos as CI artifacts. Configure your CI provider to collect the Cypress screenshots folder and the generated Mochawesome output. This gives you two recovery paths: a portable HTML report for quick review and original image files for downstream processing. Artifact paths must match the folders produced by your CI working directory; verify them in the build log rather than assuming a local path is unchanged.
- Upload the report HTML after the test command completes.
- Upload
cypress/screenshots(or your configured folder). - Preserve failure screenshots even when the test job is marked failed.
- Apply your CI system’s retention period and access controls to screenshots, which may contain customer-like data.
Multi-spec reporting with JSON (alternative pipeline)
If you need to merge results from several specs or already maintain a report-generation job, Cypress documents a JSON workflow using Mochawesome, mochawesome-merge, and mochawesome-report-generator. This is a separate reporting strategy from the screenshot reporter’s setup.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteInstall the reporting packages
npm install mochawesome mochawesome-merge mochawesome-report-generator --save-devEmit one JSON file per spec
npx cypress run --reporter mochawesome --reporter-options reportDir="cypress/results",overwrite=false,html=false,json=trueIn your Cypress reporter options, use overwrite=false, html=false, and json=true so each spec contributes a file under cypress/results.
Merge and generate HTML
npx mochawesome-merge cypress/results/*.json -o mochawesome.json
npx marge mochawesome.jsonWriting JSON, merging it, and running marge does not automatically attach Cypress screenshot files. To show screenshots, use a reporter integration that adds screenshot references or data to the test results, then ensure the final generator receives that enriched data.
Why screenshots may be missing
The report has no image at all
- Confirm the test actually reached
cy.screenshot(), or that failure screenshots are enabled. - Check the configured screenshots folder for the image.
- Verify the reporter is the active Cypress reporter, not a different reporter supplied on the command line.
The image exists beside the report but is not embedded
Set embeddedScreenshots: true under reporterOptions. A misspelled option, nesting it outside reporterOptions, or running an incompatible reporter release prevents embedding.
The HTML opens only when its asset folder is present
Enable inlineAssets: true as well as embeddedScreenshots: true. Then regenerate the report; changing the configuration does not retrofit an already-created HTML file.
Only some specs contain screenshots
Check spec-level failures and explicit screenshot commands. In a merged workflow, ensure every JSON file is included by the merge glob and that the screenshot integration runs for every spec.
The build fails before a report is produced
Compare your Cypress and Node versions with the reporter release’s compatibility table. Upgrade or select a compatible reporter release, then repeat the Cypress 10 setup. Do not rely on a version pin copied from an older article.
Images are present locally but absent in CI
Inspect the CI working directory and artifact configuration. Relative paths can differ when commands run from a subdirectory. Upload the generated HTML and screenshot directory before cleanup steps remove them.
Performance, size, and reliability considerations
Report size
Base64 embedding increases HTML size because every image is stored inside the document. Limit unnecessary full-page screenshots, avoid taking the same checkpoint repeatedly, and retain external originals when your CI system handles large artifacts better.
Capture timing
Take an explicit screenshot only after the UI assertion that proves the page is ready. This avoids embedding an intermediate loading state. Failure screenshots are valuable for diagnosis, but they do not replace assertions that wait for the relevant element.
Reproducibility
Use deterministic test data, stable selectors, and a consistent viewport. Record the Cypress and reporter versions in the build environment so a later report can be regenerated with the same compatibility assumptions.
Security and privacy
Screenshots can include tokens, names, addresses, or payment-like data rendered by a test environment. Review the image before publishing a report, restrict CI artifact access, and mask sensitive values in the application or test setup.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you need a screenshot of a website rather than a Cypress test run, ScreenshotNeo returns a PNG, JPEG, WebP, or PDF from one GET request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Example using the documented API (see the ScreenshotNeo API documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same request in 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)And 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}`);Every plan includes the features; the Free plan provides 1,000 screenshots per month without a card, Starter is $5 for 3,000, and paid plans start at $5. Create a free ScreenshotNeo account to try it.
FAQ
Does cy.screenshot() alone create a Mochawesome attachment?
It creates the Cypress image. The reporter setup is what associates that image with the test report and, with the embedding option enabled, places its data in the HTML.
Can I use this with Cypress 9 configuration files?
Use the Cypress 10-and-later setup for a Cypress 10 project. Older plugin wiring is not interchangeable; consult the reporter release documentation.
Is a merged Mochawesome JSON report automatically self-contained?
No. JSON merging combines test results. Screenshot attachment and HTML asset embedding require the appropriate integration and options.
Frequently Asked Questions
Does cy.screenshot() alone create a Mochawesome attachment?
It creates the Cypress image. The reporter setup associates it with the test and embeds it when configured.
Can I use Cypress 9 plugin wiring in Cypress 10?
No. Follow the Cypress 10-and-later setup matching your reporter release.
Does merging Mochawesome JSON automatically embed screenshots?
No. Merging combines results; screenshot integration and embedding options are separate.
Free tools Windows power users keep installed
One-click scans. No signup required.
The Bottom Line
For Cypress 10, install the community cypress-mochawesome-reporter, follow its Cypress >=10 event setup, enable embeddedScreenshots, and add inlineAssets when one standalone HTML file is required.
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.
