Cypress Custom Command typings need better documentation

Current behavior:

I am completely unable to get cypress typings to register for commands created using Cypress.Commands.add. I’ve got a repo that has several e2e projects within it that share a set of testing code (this shared lib lives at ./tools/testing). ./tools/testing/e2e/support/commands.ts is where we run several Cypress.Commands.add calls.

Alongside that file I placed a global.d.ts file (I’ve also moved it around and tried naming it index.d.ts, etc). Running tsc -p tsconfig.json --listFiles shows that the global.d.ts is included, yet it appears to have no effect. That file contains the following:

declare namespace Cypress {
  interface Chainable<Subject> {
    getIframeWindow(selector: string): Chainable<Subject>;
    getIframeBody(selector: string): Chainable<Subject>;
    replaceIFrameFetchWithXhr(selector: string): Chainable<Subject>;
  }
}

This is following this discussion (and many others that I’ve found) here

I’ve also tried wrapping the namespace declaration in a global but that doesn’t seem to help, either.

It’s clear that tsc has included my global file but I can’t discern if this is a Cypress issue or a Typescript issue.

The above commands that are created using Cypress example recipes. However, given linting, I can’t access them without using array notation or tsc will choke on them at dev time. Using dot notation to access them then throws the error:

TS2339: Property 'getIframeWindow' does not exist on type 'cy & EventEmitter'.

Desired behavior:

Improve documentation on how to add typings. It doesn’t seem realistic that there’s a whole page on how to create these commands but no expectation that people will not want typings to be supported for them.

Test code to reproduce

As this is a typings issue not a test issue I’m going to add the reproduction inline here.

Add a command:

Cypress.Commands.add('getIframeWindow', (iFrameSelector = '') => {
  cy.log(`getIframeWindow iframe${iFrameSelector}`);

  return cy
    .get(`iframe${iFrameSelector}`, { log: false })
    // @ts-ignore
    .its('0.contentWindow', { log: false })
    .should('exist', { log: false })
    .then(window => cy.wrap(window, { log: false }));
});

Type the command:

declare namespace Cypress {
  interface Chainable<Subject> {
    getIframeWindow(selector: string): Chainable<Subject>;
  }
}

Versions

Cypress 3.8.2 TS 3.4.5

[jamie--stewart]

Hi folks, this issue comment helped me work around the issue: https://github.com/cypress-io/add-cypress-custom-command-in-typescript/issues/2#issuecomment-389870033

Fix seems to be declaring Cypress in the global namespace, and your custom command definitions in there (copied from ☝️ ):

declare global {
  namespace Cypress {
    interface Chainable {
      customCommand: typeof customCommand;
    }
  }
}

function customCommand(input: MyCustomClass) {
  // ...
}

Cypress.Commands.add('customCommand', customCommand);

But agree that the solution suggested in the docs doesn’t work

[toniton]

Had a similar issue and was able to fix it by placing the custom index.d.ts file in the root directory in types folder of the cypress project and not in the support folder.

File: index.d.ts 💊

// in cypress/index.d.ts
// load type definitions that come with Cypress module
/// <reference types="cypress" />
declare namespace Cypress {
    interface Chainable {
        dataCy(value: string): Chainable<any>;
    };
}

Worked ✅

.cypress/
+---- support/
|     +---- commands.ts
.types/
+---- index.d.ts

Didn’t work ⛔

.cypress/
+---- support/
|     +---- commands.ts
|     +---- index.d.ts

TS Config 🚗

{
    "include": ["./**/*.ts", "types/**/*.d.ts"]
}