Debugging

Interactive Debugging

Cypress Test Runner shows command log with DOM snapshots at each step—click step to time travel DOM state. Pin snapshot while inspecting elements.

Open browser DevTools from Runner for console, network tab alongside Cypress command log.

• Hover commands to see before/after DOM
• Use .debug() to pause chain and inspect subject in console
• Runner shows failed assertion diff clearly

cy.pause() and cy.debug()

cy.pause() stops execution for manual inspection—remove before merging to main. cy.debug() logs subject to console and opens DevTools focus.

In CI headless runs, pause does not help—rely on screenshots and videos instead.

cy.get('[data-cy="complex-widget"]').debug();
cy.pause();

Screenshots

Cypress captures screenshot on failure automatically. cy.screenshot() manually captures named image useful mid-test for documenting bugs.

Configure screenshotsFolder and trashAssetsBeforeRuns. Attach screenshots to CI artifacts.

cy.screenshot("after-checkout-step-2");

// cypress.config.ts
screenshotOnRunFailure: true

Videos

video: true records full spec run in headless mode— invaluable for CI failures you cannot reproduce locally. Videos increase CI storage and runtime slightly.

Disable video for fast smoke jobs; enable for nightly full regression.

• Compress or retain videos limited days to control storage cost
• Combine video with test title in artifact naming for searchability
• Review video at failure timestamp from Cypress error message

export default defineConfig({
  video: true,
  videosFolder: "cypress/videos",
});

Debugging CI Failures

Compare CI vs local: viewport size, timezone, baseUrl, env vars. Run cypress run locally with same browser and config as CI.

Log cy.intercept hits and application console in support hook conditionally when CYPRESS_DEBUG env set.

afterEach(function () {
  if (this.currentTest?.state === "failed") {
    cy.screenshot("failed-" + this.currentTest.title);
  }
});