{
  "doc": {
    "id": "cloud/features/smart-orchestration/load-balancing",
    "title": "Load balancing specs in Cypress Cloud",
    "description": "Cypress Cloud automatically balances your spec files across the machines in your CI provider to minimize run time, cut CI costs, and eliminate manual tuning.",
    "section": "cloud",
    "source_path": "/llm/markdown/cloud/features/smart-orchestration/load-balancing.md",
    "version": "29f95bf8bb06f320986f3749f5bf09a35a409eab",
    "updated_at": "2026-09-04T10:49:54.630Z",
    "headings": [
      {
        "id": "cloud/features/smart-orchestration/load-balancing#load-balancing",
        "text": "Load Balancing",
        "level": 1
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#why-load-balancing-matters",
        "text": "Why load balancing matters",
        "level": 2
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#how-it-works",
        "text": "How it works",
        "level": 2
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#balance-strategy",
        "text": "Balance strategy",
        "level": 3
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#spec-duration-history-analysis",
        "text": "Spec duration history analysis",
        "level": 3
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#smart-orchestration-layered-on-top",
        "text": "Smart Orchestration layered on top",
        "level": 3
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#get-started",
        "text": "Get started",
        "level": 2
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#verifying-your-time-savings",
        "text": "Verifying your time savings",
        "level": 2
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#run-duration-analytics",
        "text": "Run Duration analytics",
        "level": 3
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#machines-view",
        "text": "Machines View",
        "level": 3
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#bar-chart-and-timeline-views",
        "text": "Bar Chart and Timeline Views",
        "level": 3
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#getting-the-most-out-of-load-balancing",
        "text": "Getting the most out of load balancing",
        "level": 2
      },
      {
        "id": "cloud/features/smart-orchestration/load-balancing#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "cloud/features/smart-orchestration/load-balancing#why-load-balancing-matters",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Why load balancing matters",
      "heading_level": 2,
      "content_markdown": "## Why load balancing matters\n\nBalanced runs finish in the shortest time your machine count allows, so pull requests are verified sooner and developers spend less time waiting on CI. Just as importantly, keeping every machine busy until the run ends means you aren't paying for idle machines. Load balancing gets the full value out of the CI resources you've already provisioned, which is often the difference between needing more machines and getting more out of the ones you have.\n\nAll of this happens automatically. Load balancing is on by default whenever you run with `--record --parallel`, with nothing to set up and nothing to keep up to date. Because Cypress balances from recent run history rather than a static configuration, it self-corrects as your suite changes: add a spec, delete a spec, or watch one get slower over time, and runs stay balanced without any hand-maintained spec lists or manual resharding. Duration is even predicted separately per browser, so runs stay balanced when the same spec behaves differently across Chrome, Firefox, Edge, or Electron.\n",
      "section": "cloud",
      "anchors": [
        "why-load-balancing-matters"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 233
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#how-it-works",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "How it works",
      "heading_level": 2,
      "content_markdown": "## How it works\n\n### Balance strategy\n\nCypress calculates which spec file to run on each machine based on the data collected from previous runs. Rather than splitting specs evenly by count, Cypress estimates the duration of each spec and distributes them so that the total run finishes as quickly as possible.\n\nAs more and more tests are recorded to the Cloud, Cypress can better predict how long a given spec file will take to run. To prevent irrelevant data from affecting the duration prediction, Cypress doesn't use old historical run data regarding the spec file, keeping estimates accurate as your application and tests evolve.\n\nRather than receiving a fixed, pre-assigned list of specs, each machine pulls the next spec from a shared, intelligently ordered queue as soon as it's free. Because work is handed out one spec at a time to whichever machine becomes available next, it naturally flows to wherever there's free capacity, so a single slow spec can't leave a machine idle while others keep working.\n\nBecause specs are distributed dynamically based on available capacity, the run order of spec files is not guaranteed when parallelized.\n\n### Spec duration history analysis\n\nWith a duration estimation for each spec file of a test run, Cypress can distribute spec files to available CI resources in descending order of spec run duration. In this manner, the most time-consuming specs start first, which minimizes the overall test run duration and keeps faster specs available to fill in any remaining gaps at the end of the run.\n\nDuration estimation is done separately for every browser the spec file is tested against. This is helpful since performance characteristics vary by browser, and therefore it is perfectly acceptable to see different duration estimates for each browser a spec file was tested against.\n\n### Smart Orchestration layered on top\n\nLoad balancing decides the default ordering, but two optional, user-configurable behaviors can modify it:\n\n*   **[Spec Prioritization](/llm/markdown/cloud/features/smart-orchestration/spec-prioritization.md)** moves specs that failed in the previous run to the front of the queue, so you get fast feedback on the specs most likely to be broken.\n*   **[Auto Cancellation](/llm/markdown/cloud/features/smart-orchestration/run-cancellation.md)** cancels the remaining specs once a configured number of tests fail. It works alongside load balancing and is configured separately.\n\nBoth are complementary to load balancing: prioritization changes _which_ specs run first, while auto cancellation decides _when_ to stop a run that's already failing.\n",
      "section": "cloud",
      "anchors": [
        "how-it-works"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 527
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#balance-strategy",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Balance strategy",
      "heading_level": 3,
      "content_markdown": "### Balance strategy\n\nCypress calculates which spec file to run on each machine based on the data collected from previous runs. Rather than splitting specs evenly by count, Cypress estimates the duration of each spec and distributes them so that the total run finishes as quickly as possible.\n\nAs more and more tests are recorded to the Cloud, Cypress can better predict how long a given spec file will take to run. To prevent irrelevant data from affecting the duration prediction, Cypress doesn't use old historical run data regarding the spec file, keeping estimates accurate as your application and tests evolve.\n\nRather than receiving a fixed, pre-assigned list of specs, each machine pulls the next spec from a shared, intelligently ordered queue as soon as it's free. Because work is handed out one spec at a time to whichever machine becomes available next, it naturally flows to wherever there's free capacity, so a single slow spec can't leave a machine idle while others keep working.\n\nBecause specs are distributed dynamically based on available capacity, the run order of spec files is not guaranteed when parallelized.\n",
      "section": "cloud",
      "anchors": [
        "balance-strategy"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 247
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#spec-duration-history-analysis",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Spec duration history analysis",
      "heading_level": 3,
      "content_markdown": "### Spec duration history analysis\n\nWith a duration estimation for each spec file of a test run, Cypress can distribute spec files to available CI resources in descending order of spec run duration. In this manner, the most time-consuming specs start first, which minimizes the overall test run duration and keeps faster specs available to fill in any remaining gaps at the end of the run.\n\nDuration estimation is done separately for every browser the spec file is tested against. This is helpful since performance characteristics vary by browser, and therefore it is perfectly acceptable to see different duration estimates for each browser a spec file was tested against.\n",
      "section": "cloud",
      "anchors": [
        "spec-duration-history-analysis"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 145
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#smart-orchestration-layered-on-top",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Smart Orchestration layered on top",
      "heading_level": 3,
      "content_markdown": "### Smart Orchestration layered on top\n\nLoad balancing decides the default ordering, but two optional, user-configurable behaviors can modify it:\n\n*   **[Spec Prioritization](/llm/markdown/cloud/features/smart-orchestration/spec-prioritization.md)** moves specs that failed in the previous run to the front of the queue, so you get fast feedback on the specs most likely to be broken.\n*   **[Auto Cancellation](/llm/markdown/cloud/features/smart-orchestration/run-cancellation.md)** cancels the remaining specs once a configured number of tests fail. It works alongside load balancing and is configured separately.\n\nBoth are complementary to load balancing: prioritization changes _which_ specs run first, while auto cancellation decides _when_ to stop a run that's already failing.\n",
      "section": "cloud",
      "anchors": [
        "smart-orchestration-layered-on-top"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 129
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#get-started",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Get started",
      "heading_level": 2,
      "content_markdown": "## Get started\n\nLoad balancing works automatically once your project is [recording to Cypress Cloud](/llm/markdown/cloud/get-started/setup.md#Setup) and running in parallel. Add the [`--parallel`](/llm/markdown/app/references/command-line.md#cypress-run-parallel) flag to your [`cypress run`](/llm/markdown/app/references/command-line.md#cypress-run) command:\n\n```\ncypress run --record --key=abc123 --parallel\n```\n\nFrom there, Cypress Cloud takes care of distributing your specs across every available machine.\n\nLoad balancing only helps when there is more than one machine to balance across, so the real prerequisite is running in parallel on multiple CI machines. See the [Parallelization guide](/llm/markdown/cloud/features/smart-orchestration/parallelization.md) for how to turn on parallelization, and the [Continuous Integration guide](/llm/markdown/app/continuous-integration/overview.md) for how to provision multiple machines with your CI provider.\n",
      "section": "cloud",
      "anchors": [
        "get-started"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 133
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#verifying-your-time-savings",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Verifying your time savings",
      "heading_level": 2,
      "content_markdown": "## Verifying your time savings\n\nYou don't have to estimate the savings yourself. Cypress Cloud measures them for you.\n\nWant a projection before you record your first run? The [Cypress Cloud Savings Calculator](https://www.cypress.io/savings-calculator?utm_source=docs.cypress.io&utm_medium=load-balancing&utm_content=Savings+Calculator) estimates the time and cost you could save from parallelization and load balancing based on your suite size and run frequency.\n\n### Run Duration analytics\n\nThe [Run Duration report](/llm/markdown/cloud/features/analytics/project-analytics.md#Run-duration) shows your **average run duration**, **average parallelization (concurrency)**, and the **time saved from parallelization** over time. This is the most direct way to confirm that load balancing is paying off, and to watch the trend as your suite and machine count change. (Only passing runs are included, so failures don't skew the numbers.)\n\n### Machines View\n\nOpen any run, select the **Specs** tab, and switch to the [Machines View](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Machines-View). When load balancing is working well, every machine finishes at roughly the same time. If one machine finishes in 3 minutes while another runs for 12, the run is bottlenecked by a single long spec, and adding more machines won't help until that imbalance is resolved.\n\n### Bar Chart and Timeline Views\n\nThe [Bar Chart View](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Bar-Chart-View) ranks specs by duration so you can spot the longest ones, while the [Timeline View](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Timeline-View) shows machines running in parallel versus sitting idle.\n",
      "section": "cloud",
      "anchors": [
        "verifying-your-time-savings"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 280
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#run-duration-analytics",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Run Duration analytics",
      "heading_level": 3,
      "content_markdown": "### Run Duration analytics\n\nThe [Run Duration report](/llm/markdown/cloud/features/analytics/project-analytics.md#Run-duration) shows your **average run duration**, **average parallelization (concurrency)**, and the **time saved from parallelization** over time. This is the most direct way to confirm that load balancing is paying off, and to watch the trend as your suite and machine count change. (Only passing runs are included, so failures don't skew the numbers.)\n",
      "section": "cloud",
      "anchors": [
        "run-duration-analytics"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 81
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#machines-view",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Machines View",
      "heading_level": 3,
      "content_markdown": "### Machines View\n\nOpen any run, select the **Specs** tab, and switch to the [Machines View](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Machines-View). When load balancing is working well, every machine finishes at roughly the same time. If one machine finishes in 3 minutes while another runs for 12, the run is bottlenecked by a single long spec, and adding more machines won't help until that imbalance is resolved.\n",
      "section": "cloud",
      "anchors": [
        "machines-view"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 83
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#bar-chart-and-timeline-views",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Bar Chart and Timeline Views",
      "heading_level": 3,
      "content_markdown": "### Bar Chart and Timeline Views\n\nThe [Bar Chart View](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Bar-Chart-View) ranks specs by duration so you can spot the longest ones, while the [Timeline View](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Timeline-View) shows machines running in parallel versus sitting idle.\n",
      "section": "cloud",
      "anchors": [
        "bar-chart-and-timeline-views"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 44
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#getting-the-most-out-of-load-balancing",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "Getting the most out of load balancing",
      "heading_level": 2,
      "content_markdown": "## Getting the most out of load balancing\n\nLoad balancing is automatic, but it can only distribute the spec files you give it. A few practices help Cypress balance your runs as efficiently as possible:\n\n*   **Keep spec durations similar.** Cypress balances _whole spec files_, so a single long spec can't be split across machines mid-run, so it strands a machine while the others wait. Aim for spec files with comparable durations. See the [test performance guide](/llm/markdown/app/guides/test-performance.md) for duration benchmarks and splitting strategies.\n*   **Split your slowest specs.** Use the [Slowest Tests](/llm/markdown/cloud/features/analytics/project-analytics.md#Slowest-tests) analytics report or the [Bar Chart View](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Bar-Chart-View) to find the specs dominating your run time, and break them into smaller, similarly sized files. Specs under ~10 seconds rarely benefit from further splitting, since per-spec overhead (browser launch, video encoding) outweighs the savings.\n*   **Match machine count to suite size.** Adding machines speeds runs up only until the workload is evenly balanced. Use the [Machines View](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Machines-View) to confirm machines are well utilized before scaling further. Cypress Cloud also surfaces a [Recommendations](/llm/markdown/cloud/features/recorded-runs.md#Recommendations) panel on each run that models your run time at different machine counts. For example, it estimating how much faster a run would be with more machines, or flagging when you're using more than you need.\n*   **Combine with the other Smart Orchestration features.** [Spec Prioritization](/llm/markdown/cloud/features/smart-orchestration/spec-prioritization.md) and [Auto Cancellation](/llm/markdown/cloud/features/smart-orchestration/run-cancellation.md) surface failures faster and stop wasting machine-minutes on runs that are already broken.\n",
      "section": "cloud",
      "anchors": [
        "getting-the-most-out-of-load-balancing"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 312
    },
    {
      "id": "cloud/features/smart-orchestration/load-balancing#see-also",
      "doc_id": "cloud/features/smart-orchestration/load-balancing",
      "heading": "See also",
      "heading_level": 2,
      "content_markdown": "## See also\n\n*   [Parallelization](/llm/markdown/cloud/features/smart-orchestration/parallelization.md): Run spec files simultaneously across machines and visualize the results in Cypress Cloud.\n*   [Smart Orchestration Overview](/llm/markdown/cloud/features/smart-orchestration/overview.md): See how load balancing fits alongside Cypress Cloud's other orchestration features.\n*   [Spec Prioritization](/llm/markdown/cloud/features/smart-orchestration/spec-prioritization.md): Run specs that failed in the previous run first for faster feedback.\n*   [Auto Cancellation](/llm/markdown/cloud/features/smart-orchestration/run-cancellation.md): Cancel a run once a set number of tests fail to save CI resources.\n*   [Test Performance guide](/llm/markdown/app/guides/test-performance.md): Benchmarks and strategies for splitting specs so they balance more efficiently.\n",
      "section": "cloud",
      "anchors": [
        "see-also"
      ],
      "path": "/llm/json/chunked/cloud/features/smart-orchestration/load-balancing.json",
      "token_estimate": 107
    }
  ]
}