Inside the Driver: Commands, Queries, and the Retry Engine

When you write cy.get('.btn').click(), you're interacting with the Cypress driver — a sophisticated execution engine that runs inside the browser. The driver doesn't simply find an element and click it. It enqueues two commands into a linked-list queue, waits for the page to stabilize, retries the query until the element exists (or times out), verifies upcoming assertions, and only then dispatches the click. This article dissects that engine.

The $Cypress Object: Assembling the Runtime

The browser-side entry point is packages/driver/src/main.ts, which imports configuration patches (Bluebird, jQuery, Lodash), then imports and re-exports $Cypress — the composition root for the entire browser-side runtime.

packages/driver/src/cypress.ts assembles an impressive number of concerns:

graph TD
    CYPRESS["$Cypress<br/>Composition Root"]
    COMMANDS["$Commands<br/>30+ command modules"]
    CY["$Cy<br/>Command executor"]
    RUNNER["$Runner<br/>Mocha integration"]
    SERVER["$Server<br/>Socket.IO transport"]
    MOCHA["$Mocha<br/>Test framework wrapper"]
    LOG["Log<br/>Command logging"]
    CHAINER["$Chainer<br/>Fluent API (.get().click())"]
    COMMAND["$Command<br/>Command state machine"]
    COOKIES["$Cookies<br/>Cookie management"]

    CYPRESS --> COMMANDS
    CYPRESS --> CY
    CYPRESS --> RUNNER
    CYPRESS --> SERVER
    CYPRESS --> MOCHA
    CYPRESS --> LOG
    CYPRESS --> CHAINER
    CYPRESS --> COMMAND
    CYPRESS --> COOKIES

The file imports from over 30 modules spanning browser info, script utilities, source map handling, DOM helpers, error messages, keyboard simulation, cross-origin communication, and telemetry. It defines global types (putting Cypress and cy on the Window interface) and sets up the jQuery proxy function that makes Cypress.$() work.

Tip: The $ prefix on class names ($Cypress, $Cy, $Command) is a Cypress convention for distinguishing framework internals from user-facing APIs. When you see $Cy, think "the internal class that implements cy."

$Cy and the Mixin Architecture

The $Cy class is arguably the most important class in the entire codebase. It extends EventEmitter2 and implements a staggering ~15 interfaces via a mixin pattern:

export class $Cy extends EventEmitter2
  implements ITimeouts, IStability, IAssertions, IRetries,
    IJQuery, ILocation, ITimer, IChai, IXhr, IAliases,
    ICySnapshots, ICyFocused {

Each interface corresponds to a focused module that exports a create() factory function:

Interface	Module	Purpose
ITimeouts	cy/timeouts.ts	Command timeout management
IStability	cy/stability.ts	Page load/transition detection
IAssertions	cy/assertions.ts	Assertion verification
IRetries	cy/retries.ts	Retry loop engine
IJQuery	cy/jquery.ts	jQuery instance management
ILocation	cy/location.ts	URL/location helpers
ITimer	cy/timers.ts	Timer pause/resume
IChai	cy/chai.ts	Chai assertion library integration
IXhr	cy/xhrs.ts	XHR tracking (legacy)
IAliases	cy/aliases.ts	cy.as() alias management
ISnapshots	cy/snapshots.ts	DOM snapshot capture
IFocused	cy/focused.ts	Focus/blur management

The mixin imports at the top of cy.ts reveal this pattern clearly — each module is imported with its create function and corresponding interface type. During $Cy construction, each create() function is called with the shared state, and the returned methods are mixed onto the $Cy instance.

This architecture trades discoverability for composability. You can't Ctrl+Click on this.retry() and jump directly to its implementation because it's mixed in at runtime. But each concern is cleanly isolated in its own file, and the interface declarations on the class serve as documentation.

Command Registration and the Commands Barrel

The 30+ command modules live in packages/driver/src/cy/commands/. The barrel file at packages/driver/src/cy/commands/index.ts exports them all as allCommands:

export const allCommands = {
  ...Actions,        // click, type, check, select, scroll, etc.
  Agents,            // cy.spy(), cy.stub()
  Aliasing,          // cy.as()
  Asserting,         // cy.should(), cy.and()
  Clock,             // cy.clock(), cy.tick()
  Commands,          // Cypress.Commands.add()
  Connectors,        // cy.then(), cy.each(), cy.spread()
  Cookies,           // cy.getCookie(), cy.setCookie()
  Debugging,         // cy.debug(), cy.pause()
  // ...20+ more modules
  ...Querying,       // cy.get(), cy.contains(), cy.find()
  Window,            // cy.window(), cy.document(), cy.title()
  Xhr,               // cy.route() (legacy)
}

Notice that Actions and Querying use spread syntax (...) — this is because they export multiple named modules rather than a single default. Each command module exports a definition object that specifies the command name, whether it's a query or action, its prevSubject requirements, and its implementation function.

$Command Lifecycle and State Machine

Every cy.* call creates a $Command instance. The command has a simple but important state machine:

stateDiagram-v2
    [*] --> queued: new $Command()
    queued --> pending: command.start()
    pending --> passed: command.pass()
    pending --> failed: command.fail()
    pending --> recovered: command.recovered()
    pending --> skipped: command.skip()

export class $Command {
  attributes!: Record<string, any>
  state: 'queued' | 'pending' | 'passed' | 'recovered' | 'failed' | 'skipped'

Each state transition is a simple method call — pass(), fail(), recovered(), skip(), start(). The attributes bag carries everything the command needs: its name, arguments, chainer ID, timeout, logs, the previous/next command references (forming the linked list), and the subject chain.

The set() method accepts either a key-value pair or an object, using _.extend to merge into attributes. This flexibility is used extensively — commands accumulate metadata as they flow through the queue.

The finishLogs() method is called when a command completes, ensuring all log entries get their final snapshots and any deferred errors are materialized. This is part of the command log that appears in the Cypress test runner UI.

CommandQueue: Linked-List Execution with Nested Insertion

The CommandQueue extends a generic Queue class and manages the ordered execution of commands. Two features make it unique:

Linked-list structure: When commands are inserted, prev and next references are maintained between adjacent commands. The insert() method updates both the new command and its neighbors:

insert(index: number, command: $Command) {
  super.insert(index, command)
  const prev = this.at(index - 1)
  const next = this.at(index + 1)
  if (prev) {
    prev.set('next', command)
    command.set('prev', prev)
  }
  if (next) {
    next.set('prev', command)
    command.set('next', next)
  }
}

Nested insertion via nestedIndex: When a command's implementation enqueues child commands (as custom commands and .within() do), those children need to execute before subsequent commands in the outer chain. The enqueue() method uses state('nestedIndex') to insert new commands at the correct position rather than appending to the end.

flowchart TD
    subgraph "Initial Queue"
        A["cy.get('.form')"] --> B["cy.submit()"]
    end

    subgraph "After .get enqueues children"
        A2["cy.get('.form')"] --> C["(nested) find DOM"] --> D["(nested) verify"] --> B2["cy.submit()"]
    end

Query vs Action: The Retry Contract

This is the most important design distinction in the driver. The comment in command_queue.ts explains it clearly:

Queries are simple beasts: They take arguments, and return an idempotent function. They contain no retry logic, have no awareness of cy.stop(), and are entirely synchronous.

Queries (like cy.get(), cy.contains(), cy.find()) must return a synchronous, idempotent function. This function takes a subject and returns a new subject. Because it's idempotent, Cypress can call it repeatedly during retries without side effects.

Actions (like cy.click(), cy.type(), cy.visit()) can have side effects and can enqueue new commands. But they cannot be nested inside queries — if a query tries to invoke an action, the driver throws immediately:

const commandEnqueued = (obj) => {
  if (isQuery && !obj.query) {
    $errUtils.throwErrByPath('query_command.invoked_action', {
      args: { name, action: obj.name },
    })
  }
}

The retryQuery() function at line 72-112 enforces this contract. It verifies the query returned a function (not a promise, not a primitive), then delegates to cy.verifyUpcomingAssertions() which runs the assertion chain. If assertions fail, the retry mechanism kicks in.

The Retry Engine

The retry implementation in packages/driver/src/cy/retries.ts is deceptively simple but critically important. Here's what happens:

1. Mocha's timeout is removed: The first thing retry() does is call clearTimeout(), removing Mocha's built-in runnable timeout. Cypress manages timing itself.

2. A 16ms interval is established: The default _interval is 16ms (approximately one frame at 60fps). This means Cypress retries queries ~60 times per second.

3. Time tracking: Each retry calculates total = Date.now() - options._start and checks if (total + interval) >= options._runnableTimeout. If so, it throws with the accumulated error.

4. Stability awareness: If state('isStable') is false (meaning a page transition is happening), the start time is reset. This ensures timeouts don't count time spent waiting for page loads.

sequenceDiagram
    participant CQ as CommandQueue
    participant Retry as retries.ts
    participant Query as Query Function
    participant Assert as Assertions

    CQ->>Query: Execute query(subject)
    Query-->>CQ: Return new subject
    CQ->>Assert: Verify assertions
    Assert-->>CQ: Assertion failed!
    CQ->>Retry: retry(fn, options)
    Retry->>Retry: clearTimeout (remove Mocha timeout)
    Retry->>Retry: Wait 16ms
    Retry->>Query: Re-execute query(subject)
    Query-->>Assert: New subject
    Assert-->>CQ: Assertion passed!

The retry function returns a Promise.delay(interval).then(...) chain, creating a polling loop. After each delay, it checks if the runnable has changed (test moved on), if the promise was canceled, or if the page became unstable. If none of those, it invokes the original function again via whenStable(fn).

Tip: The 16ms retry interval explains why Cypress feels responsive — it's checking for changes at roughly the display refresh rate. If you need to debug retry behavior, the cypress:driver:errors debug namespace logs every retry attempt.

What's Next

The driver executes commands in the browser, but it needs a browser to run in. In Part 5, we'll explore how Cypress detects installed browsers, launches them with the right flags and extensions, and automates them through CDP — the Chrome DevTools Protocol that provides low-level browser control.