How to add timestamps to Cypress screenshot filenames

For a screenshot you capture explicitly, generate a filename-safe timestamp and pass it to cy.screenshot():

const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
cy.screenshot(`checkout-${timestamp}`)

This produces a filename like checkout-2026-10-03T20-34-05-046Z.png. The ISO timestamp is UTC, indicated by the trailing Z. For automatic test-failure screenshots, Cypress chooses the name; use the Node after:screenshot event for centralized post-capture handling. See the Cypress screenshot command and Node events documentation.

Timestamp a manual screenshot

Cypress uses a supplied screenshot name instead of its default suite and test name. A name can include a subdirectory path, and Cypress creates that directory structure.

it('captures checkout', () => {
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
  cy.screenshot(`checkout-${timestamp}`)
})

Use a small helper if several tests need the same convention:

const filenameTimestamp = () =>
  new Date().toISOString().replace(/[:.]/g, '-')

const captureTimestamped = (name, options) =>
  cy.screenshot(`${name}-${filenameTimestamp()}`, options)

// In a test:
captureTimestamped('checkout')

The helper is ordinary JavaScript around Cypress’s screenshot command. Keep the timestamp generation in the test process and pass the final name to Cypress.

Choose a timestamp format

• UTC ISO style: replacing colons and periods retains the readable T and Z markers and sorts chronologically.
• Strictly portable filename: replace the markers too: new Date().toISOString().replace(/[^0-9]/g, '-'). This produces only digits and hyphens, at the cost of less obvious UTC notation.
• Local time: construct the timestamp from local date components only if a local timezone is a firm requirement. Local times can be ambiguous around daylight-saving changes; UTC avoids that ambiguity.

Do not use a raw ISO string as a filename if your tooling or target filesystem treats colons specially.

Automatic failure screenshots

Cypress automatically captures screenshots for test failures during cypress run, but not during cypress open. The automatic filename is controlled by Cypress and may include duplicate, failure, and retry suffixes. A timestamp in a manual cy.screenshot() call does not rename these automatic artifacts.

For centralized post-save work, register the Node event in your Cypress configuration. The event receives the screenshot details after the file has been written, including its path:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('after:screenshot', (details) => {
        console.log('Screenshot saved:', details.path)
        // Perform post-capture work here.
        // Return details if modifying supported screenshot details.
        return details
      })
      return config
    },
  },
})

This example logs the actual path. The event is a post-capture hook, not a documented filename-template setting. If your requirement is to rename the file, consult the current event arguments and return behavior, use the supplied path, and preserve Cypress’s artifact reporting expectations. Avoid reconstructing a path from a guessed spec directory.

The default screenshot directory is cypress/screenshots. Cypress derives paths using the spec location and common ancestor of the specs selected for the run, so paths can change with the selected spec set. Cypress also clears the screenshots folder before cypress run by default; set trashAssetsBeforeRuns: false if the run must retain existing screenshot assets. See the screenshots and videos guide, configuration reference, and test organization guide.

Options and edge cases

Need	Approach	Keep in mind
Name explicit captures	Include a timestamp in each cy.screenshot(name) call or shared helper.	This does not set names for automatic failure captures.
Handle automatic captures centrally	Use the Node after:screenshot event and its provided path.	It runs after the file is saved; treat rename operations carefully.
Avoid likely collisions	Include a test or scenario label alongside the timestamp.	Clock resolution and skew mean timestamps alone are not a strict uniqueness guarantee.
Require strict uniqueness	Add a sequence or random component to the name.	Keep the component safe for filenames and useful for tracing the test.
Retain old run artifacts	Set trashAssetsBeforeRuns: false.	Manage stale files yourself so results from different runs are not confused.

Cypress can append its own suffixes for duplicate names, failures, and retries. Do not assume a custom timestamp removes those suffix rules; see test retries.

Troubleshooting

Symptom	Likely cause	Fix
The failure screenshot has no timestamp.	The timestamp was only passed to a manual screenshot call.	Use the Node after:screenshot event for centralized handling of saved screenshots.
The screenshot appears in an unexpected folder.	Cypress computes paths from the spec location and selected specs’ common ancestor.	Use the actual details.path supplied by the event; check which specs the run selected.
Old screenshots disappeared.	cypress run clears the screenshot folder by default.	Configure trashAssetsBeforeRuns: false when retaining existing assets is required.
Two files have similar or duplicate names.	Captures can occur within the same timestamp resolution, or Cypress can apply its suffix rules.	Add a test identifier and, when strict uniqueness matters, a sequence or random component.
Renamed file is missing from reported artifacts.	Filesystem changes did not preserve Cypress’s expected artifact path or event behavior.	Follow the current event return contract, use the supplied path, and verify downstream consumers use the final path.
Timestamp order looks wrong across machines.	Local time zones or inaccurate system clocks differ.	Use UTC ISO timestamps and keep the Z marker; synchronize machine clocks where ordering matters.

Performance, reliability, and cost

Formatting an ISO timestamp is negligible compared with loading a page and capturing it. Reliability depends more on naming collisions, clock accuracy, cleanup behavior, and preserving the path Cypress reports. Use UTC for cross-machine sorting, add an identifier for concurrent tests, and use Cypress’s supplied saved path in Node-side handling.

Cypress’s timestamp naming is part of your test code and local artifact workflow. If your separate task is capturing public websites through an API, ScreenshotNeo is a website screenshot API and MCP server: one GET request can return PNG, JPEG, WebP, or PDF. It does not change how Cypress names its test artifacts.

Or skip the browser setup

For a website screenshot from an API, ScreenshotNeo takes a URL in one request. Full options are in the ScreenshotNeo documentation.

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

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.

FAQ

Does the timestamp include the timezone?

toISOString() produces UTC time and ends in Z.

Can I timestamp Cypress’s automatic failure screenshot using only cy.screenshot()?

No. That names an explicit capture. Automatic failure captures need centralized post-save handling through the Node event route.

Will adding a timestamp stop Cypress from appending suffixes?

No. Cypress may add duplicate, failure, or retry suffixes according to its screenshot behavior.