{
  "doc": {
    "id": "accessibility/guides/local-development",
    "title": "Accessibility feedback during local development",
    "description": "Record one spec from your machine to get a full Cypress Accessibility report without waiting for CI: confirm a fix, catch the violation it introduced, and compare against your base branch before you push.",
    "section": "accessibility",
    "source_path": "/llm/markdown/accessibility/guides/local-development.md",
    "version": "066c46e056f0f322a0670d2d3aa4e6adaebfe717",
    "updated_at": "2026-09-10T13:30:12.426Z",
    "headings": [
      {
        "id": "accessibility/guides/local-development#accessibility-feedback-during-local-development",
        "text": "Accessibility feedback during local development",
        "level": 1
      },
      {
        "id": "accessibility/guides/local-development#record-the-specs-youre-working-on",
        "text": "Record the specs you're working on",
        "level": 2
      },
      {
        "id": "accessibility/guides/local-development#when-the-report-is-ready",
        "text": "When the report is ready",
        "level": 2
      },
      {
        "id": "accessibility/guides/local-development#compare-two-local-runs-to-prove-a-fix-landed",
        "text": "Compare two local runs to prove a fix landed",
        "level": 2
      },
      {
        "id": "accessibility/guides/local-development#make-your-configuration-match-localhost",
        "text": "Make your configuration match localhost",
        "level": 2
      },
      {
        "id": "accessibility/guides/local-development#keep-local-runs-from-cluttering-the-project",
        "text": "Keep local runs from cluttering the project",
        "level": 2
      },
      {
        "id": "accessibility/guides/local-development#what-a-local-run-cant-do",
        "text": "What a local run can't do",
        "level": 2
      },
      {
        "id": "accessibility/guides/local-development#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "accessibility/guides/local-development#record-the-specs-youre-working-on",
      "doc_id": "accessibility/guides/local-development",
      "heading": "Record the specs you're working on",
      "heading_level": 2,
      "content_markdown": "## Record the specs you're working on\n\nRecord only the specs that exercise the code you changed:\n\n*   npm\n*   Yarn\n*   pnpm\n*   Bun\n\n```\nnpx cypress run --record --key <record_key> --spec \"cypress/e2e/checkout.cy.js\"\n```\n\n```\nyarn cypress run --record --key <record_key> --spec \"cypress/e2e/checkout.cy.js\"\n```\n\n```\npnpm cypress run --record --key <record_key> --spec \"cypress/e2e/checkout.cy.js\"\n```\n\n```\nbunx cypress run --record --key <record_key> --spec \"cypress/e2e/checkout.cy.js\"\n```\n\nRecording is what produces the report, so this has to be `cypress run --record`. Interactive mode (`cypress open`) never records a run to Cypress Cloud, so it never generates accessibility results.\n\nWhen the run finishes, Cypress prints its URL at the end of the run summary:\n\n```\n  ────────────────────────────────────────────────────────────────────────────────\n\n  Recorded Run: https://cloud.cypress.io/projects/7s5okt/runs/1042\n```\n\nOpen that URL and go to the **Accessibility** tab.\n\n`CYPRESS_RECORD_KEY` must be set as an actual operating system environment variable (for example via `export CYPRESS_RECORD_KEY=...` or your CI provider's secrets). Cypress reads it directly from your shell or CI environment — it is **not** read from `cypress.env.json` or the `env` block of your Cypress configuration, since those only populate test environment variables. If you don't want to set an environment variable, pass the key inline with the `--key` flag instead.\n\nNothing else is required.\n\nThe requirements are the same as for any recorded run, with one that catches people locally: reports need a Chromium-based or Electron browser, so a habit of running `--browser firefox` locally produces no report at all. See [No accessibility report was generated for a run](/llm/markdown/accessibility/troubleshooting.md#No-accessibility-report-was-generated-for-a-run) for the full list.\n\nTo stay in your editor for the whole loop rather than switching to the browser after each recording, configure [Cypress Cloud MCP](/llm/markdown/cloud/integrations/cloud-mcp.md) and ask your agent for the run's results. See [Work with AI agents](/llm/markdown/accessibility/work-with-ai-agents.md) for prompt patterns.\n",
      "section": "accessibility",
      "anchors": [
        "record-the-specs-youre-working-on"
      ],
      "path": "/llm/json/chunked/accessibility/guides/local-development.json",
      "token_estimate": 384
    },
    {
      "id": "accessibility/guides/local-development#when-the-report-is-ready",
      "doc_id": "accessibility/guides/local-development",
      "heading": "When the report is ready",
      "heading_level": 2,
      "content_markdown": "## When the report is ready\n\nEach spec's data starts processing as soon as that spec finishes uploading, but the run-level report is assembled only once Cypress Cloud marks the run **complete**.\n\nFor grouped and parallelized runs, completion waits out the project's [Run Completion Delay](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Run-Completion-Delay), a grace period (60 seconds by default) that lets late machines join the run before it closes. Report finalization waits with it, so on a CI run the accessibility report can trail the last machine by that much.\n\nA single local run without `--group` or `--parallel` skips the delay entirely. Cypress Cloud completes it as soon as its specs are done, which is why the loop on this page stays fast. You inherit the delay only when you reproduce a CI invocation locally with grouping or parallelization. If you do, shorten the delay in [project settings](/llm/markdown/cloud/account-management/projects.md#Run-Completion-Delay) or close the run yourself with the [Run Completion API](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Run-Completion-API).\n",
      "section": "accessibility",
      "anchors": [
        "when-the-report-is-ready"
      ],
      "path": "/llm/json/chunked/accessibility/guides/local-development.json",
      "token_estimate": 201
    },
    {
      "id": "accessibility/guides/local-development#compare-two-local-runs-to-prove-a-fix-landed",
      "doc_id": "accessibility/guides/local-development",
      "heading": "Compare two local runs to prove a fix landed",
      "heading_level": 2,
      "content_markdown": "## Compare two local runs to prove a fix landed\n\nSeeing zero violations for the rule you fixed is weaker evidence than seeing that rule move from failing to resolved. [Branch Review](/llm/markdown/accessibility/guides/compare-reports.md) gives you that, and it works just as well with two runs recorded from your own machine. Cypress reads your branch and commit from your local `.git` directory on every recorded run, whether or not it detects a CI provider, so local runs land on the correct branch and can be compared like any other run.\n\n1.  Record the specs from your base branch first, before you start work, or by stashing your changes:\n    \n    *   npm\n    *   Yarn\n    *   pnpm\n    *   Bun\n    \n    ```\n    npx cypress run --record --spec \"cypress/e2e/checkout.cy.js\"\n    ```\n    \n    ```\n    yarn cypress run --record --spec \"cypress/e2e/checkout.cy.js\"\n    ```\n    \n    ```\n    pnpm cypress run --record --spec \"cypress/e2e/checkout.cy.js\"\n    ```\n    \n    ```\n    bunx cypress run --record --spec \"cypress/e2e/checkout.cy.js\"\n    ```\n    \n2.  Make your fix, then record the same specs again from your branch.\n    \n3.  In Cypress Cloud, open Branch Review with your branch's run as the Changed run and the base branch's run as the Base run.\n    \n\nThe **Resolved elements** section should list the rule you worked on in every view where it was failing, which is how you confirm the fix reached more than the one element you tested by hand. The **New failed elements** section is the more valuable half: it's where the `aria-label` that duplicates visible text shows up.\n\nRecording the **same specs** in both runs is what makes the comparison trustworthy. Branch Review compares what each run actually saw, so a base run covering the whole suite and a changed run covering one spec produces a long list of \"resolved\" elements that only means those pages weren't visited.\n\nThe score for a two-spec local run isn't comparable to the score for a full CI run. A run's [accessibility score](/llm/markdown/accessibility/core-concepts/accessibility-score.md) averages every snapshot in that run, so changing which specs ran changes the denominator. Compare rules and element counts between local runs, and leave score tracking to your full suite.\n",
      "section": "accessibility",
      "anchors": [
        "compare-two-local-runs-to-prove-a-fix-landed"
      ],
      "path": "/llm/json/chunked/accessibility/guides/local-development.json",
      "token_estimate": 452
    },
    {
      "id": "accessibility/guides/local-development#make-your-configuration-match-localhost",
      "doc_id": "accessibility/guides/local-development",
      "heading": "Make your configuration match localhost",
      "heading_level": 2,
      "content_markdown": "## Make your configuration match localhost\n\nThe one thing that may differ between a local run and a CI run is the URL your tests visit. [`viewFilters`](/llm/markdown/accessibility/configuration/viewfilters.md) patterns that name a hostname match that hostname exactly, so a configuration written for a deployed environment silently stops applying when you run against `http://localhost:3000`. Pages you meant to exclude reappear, and the local report stops matching the one your team sees in CI.\n\nPath-only patterns match any hostname, so they work in both places:\n\nApp Quality Config\n\n```\n{\n  \"viewFilters\": [\n    {\n      \"pattern\": \"/auth/*\",\n      \"include\": false,\n      \"comment\": \"Hosted sign-in provider, out of scope. Path-only so it matches localhost and deployed environments alike\"\n    }\n  ]\n}\n```\n\nWhen a rule has to name a hostname, add a [profile](/llm/markdown/accessibility/configuration/profiles.md) for local runs and override just that setting:\n\nApp Quality Config\n\n```\n{\n  \"viewFilters\": [\n    { \"pattern\": \"https://app.example.com/*\", \"include\": true },\n    {\n      \"pattern\": \"*\",\n      \"include\": false,\n      \"comment\": \"Report only on our own application\"\n    }\n  ],\n  \"profiles\": [\n    {\n      \"name\": \"aq-config-local\",\n      \"comment\": \"Local runs serve the app from localhost, so the hostname rules above never match\",\n      \"config\": {\n        \"viewFilters\": [\n          { \"pattern\": \"http://localhost:*/*\", \"include\": true },\n          { \"pattern\": \"*\", \"include\": false }\n        ]\n      }\n    }\n  ]\n}\n```\n\nSelect the profile by tagging the run:\n\n*   npm\n*   Yarn\n*   pnpm\n*   Bun\n\n```\nnpx cypress run --record --tag \"aq-config-local\" --spec \"cypress/e2e/checkout.cy.js\"\n```\n\n```\nyarn cypress run --record --tag \"aq-config-local\" --spec \"cypress/e2e/checkout.cy.js\"\n```\n\n```\npnpm cypress run --record --tag \"aq-config-local\" --spec \"cypress/e2e/checkout.cy.js\"\n```\n\n```\nbunx cypress run --record --tag \"aq-config-local\" --spec \"cypress/e2e/checkout.cy.js\"\n```\n\nA profile replaces each setting it defines rather than merging with it, so repeat any base rules the local run still needs. See [`profiles`](/llm/markdown/accessibility/configuration/profiles.md) for how selection and overriding work.\n",
      "section": "accessibility",
      "anchors": [
        "make-your-configuration-match-localhost"
      ],
      "path": "/llm/json/chunked/accessibility/guides/local-development.json",
      "token_estimate": 383
    },
    {
      "id": "accessibility/guides/local-development#keep-local-runs-from-cluttering-the-project",
      "doc_id": "accessibility/guides/local-development",
      "heading": "Keep local runs from cluttering the project",
      "heading_level": 2,
      "content_markdown": "## Keep local runs from cluttering the project\n\nLocal runs land in the same project as your CI runs, and their reports are just as real. To keep them recognizable, tag them:\n\n*   npm\n*   Yarn\n*   pnpm\n*   Bun\n\n```\nnpx cypress run --record --tag \"local\" --spec \"cypress/e2e/checkout.cy.js\"\n```\n\n```\nyarn cypress run --record --tag \"local\" --spec \"cypress/e2e/checkout.cy.js\"\n```\n\n```\npnpm cypress run --record --tag \"local\" --spec \"cypress/e2e/checkout.cy.js\"\n```\n\n```\nbunx cypress run --record --tag \"local\" --spec \"cypress/e2e/checkout.cy.js\"\n```\n\nTags are shown on the run and are filterable in Cypress Cloud, so a shared `local` tag lets anyone skip past them when scanning the run list.\n\nEvery recorded run also consumes [test results](/llm/markdown/cloud/account-management/billing-and-usage.md#Cloud-test-results) from your plan, whether it came from CI or your laptop. That's an argument for narrow `--spec` runs, which you want anyway.\n",
      "section": "accessibility",
      "anchors": [
        "keep-local-runs-from-cluttering-the-project"
      ],
      "path": "/llm/json/chunked/accessibility/guides/local-development.json",
      "token_estimate": 181
    },
    {
      "id": "accessibility/guides/local-development#what-a-local-run-cant-do",
      "doc_id": "accessibility/guides/local-development",
      "heading": "What a local run can't do",
      "heading_level": 2,
      "content_markdown": "## What a local run can't do\n\nThe [Results API](/llm/markdown/accessibility/connect-and-extend/results-api.md) is a CI tool and doesn't have a local equivalent. `getAccessibilityResults()` identifies the run to report on from the CI environment variables present when the run was recorded, so calling it from your machine fails with \"It appears you are not running in CI.\" Keep policy enforcement in your pipeline and use Cypress Cloud, Branch Review, or Cloud MCP for local feedback.\n",
      "section": "accessibility",
      "anchors": [
        "what-a-local-run-cant-do"
      ],
      "path": "/llm/json/chunked/accessibility/guides/local-development.json",
      "token_estimate": 96
    },
    {
      "id": "accessibility/guides/local-development#see-also",
      "doc_id": "accessibility/guides/local-development",
      "heading": "See also",
      "heading_level": 2,
      "content_markdown": "## See also\n\n*   [Compare reports](/llm/markdown/accessibility/guides/compare-reports.md) is the full guide to Branch Review for Cypress Accessibility.\n*   [Catch accessibility regressions](/llm/markdown/accessibility/guides/detect-changes.md) covers the other ways to catch one, including scheduled runs, CI policies, and analytics.\n*   [Fix accessibility violations](/llm/markdown/accessibility/guides/improve-accessibility.md) is the workflow this page speeds up: pick a rule, fix it, prove it landed.\n*   [How Cypress Accessibility works](/llm/markdown/accessibility/core-concepts/how-it-works.md) explains the recording, processing, and reporting stages.\n*   [`profiles`](/llm/markdown/accessibility/configuration/profiles.md) documents run-tag-based configuration overrides in full.\n*   [`viewFilters`](/llm/markdown/accessibility/configuration/viewfilters.md) covers URL pattern matching, including path-only patterns.\n*   [Work with AI agents](/llm/markdown/accessibility/work-with-ai-agents.md) has more Cypress Cloud MCP prompt patterns.\n*   [Block pull requests and set policies](/llm/markdown/accessibility/guides/block-pull-requests.md) is where the Results API belongs, once local feedback is in place.\n*   [Troubleshooting](/llm/markdown/accessibility/troubleshooting.md) covers reports that are missing or don't match what you expect.\n*   [Cypress Accessibility FAQ](/llm/markdown/accessibility/faq.md) answers focused questions about local runs, scoring, and configuration.\n",
      "section": "accessibility",
      "anchors": [
        "see-also"
      ],
      "path": "/llm/json/chunked/accessibility/guides/local-development.json",
      "token_estimate": 185
    }
  ]
}