如何强制TypeScript检查cy.task的参数类型？

Problem Description #

I've defined TypeScript types for my custom Cypress task like this:

// X and Y represent specific types
function a(arg: X): Y { ... }
...
on('task', { a })
declare global {
  namespace Cypress {
    interface Chainable {
      task(event: 'a', arg: X): Chainable<Y>;
    }
  }
}

But I found that TypeScript incorrectly accepts code like cy.task('a', notAnX) — it falls back to the default overload in cypress.d.ts:

task<S = unknown>(event: string, arg?: any, options?: Partial<Loggable & Timeoutable>): Chainable<S>

I'm wondering if there's a way to modify the type declarations so that this incorrect usage triggers a TypeScript error?

As an update: I've seen similar discussions around this need, but haven't found a viable solution yet. My current guess is that the only way to achieve this is to copy cypress.d.ts and remove that default overload.

Solution & Analysis #

You're absolutely right about the root cause: TypeScript treats the string literal 'a' as a subtype of string, so it will always match the default event: string overload first, bypassing your custom typed overload. Unfortunately, there's no official, clean way to override or disable this default overload right now.

Let's break down your options:

1. Full Override (Most Strict, High Maintenance)

Copying cypress.d.ts and removing the loose event: string overload is indeed the most thorough way to enforce strict type checking. However, this approach comes with downsides:

• You'll need to maintain your own copy of Cypress's type definitions, which means syncing it every time Cypress releases an update to avoid missing new features or type fixes.
• It adds ongoing maintenance overhead to your project.

2. Custom Command Wrapper (Balanced Approach)

A more practical middle ground is to wrap your custom task in a dedicated Cypress command. This lets you fully control parameter and return types without modifying Cypress's core type files:

declare global {
  namespace Cypress {
    interface Chainable {
      runTaskA(arg: X): Chainable<Y>;
    }
  }
}

Cypress.Commands.add('runTaskA', (arg: X) => {
  return cy.task('a', arg);
});

Now, when you call cy.runTaskA(notAnX), TypeScript will immediately throw an error for mismatched argument types. This keeps your type safety intact while avoiding the hassle of maintaining a custom cypress.d.ts file.

3. Type Assertions (Quick Fix, Limited Safety)

If you want a lightweight workaround without adding new commands, you can use type assertions to narrow down the types at call time. Pair this with ESLint rules like @typescript-eslint/no-explicit-any to prevent lazy type usage:

cy.task('a', notAnX as X).then((result: Y) => {
  // Handle result with strict type checks
});

This won't catch the error at the task call itself, but it will enforce type safety when you process the result later.

内容的提问来源于stack exchange，提问作者Alexey Romanov