From 07b383865162af7bcba29778f9cb7a021091b64c Mon Sep 17 00:00:00 2001 From: Gleb Bahmutov Date: Tue, 23 Jul 2019 11:40:45 -0400 Subject: [PATCH 1/3] expand typescript and custom commands example --- source/guides/tooling/typescript-support.md | 47 +++++++++++++++++++-- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/source/guides/tooling/typescript-support.md b/source/guides/tooling/typescript-support.md index 4777ef0a43..f05ae61cc8 100644 --- a/source/guides/tooling/typescript-support.md +++ b/source/guides/tooling/typescript-support.md @@ -45,11 +45,52 @@ You can find an example of Jest and Cypress installed in the same project using ## Types for custom commands -When adding custom commands to the `cy` object, you can add their types to avoid TypeScript errors. You can find the simplest implementation of Cypress and TypeScript in this {% url "repo example here" https://github.com/omerose/cypress-support %}. +When adding custom commands to the `cy` object, you can add their types to avoid TypeScript errors. For example if you add method `cy.dataCy` in `cypress/support/index.js` like this: -## TODO MVC Example Repo +```javascript +// cypress/support/index.js +Cypress.Commands.add('dataCy', (value) => cy.get(`[data-cy=${value}]`)) +``` + +Then you can add the method `dataCy` to the global Cypress `Chainable` interface (so called because commands are chained together) by creating a file `cypress/support/index.d.ts`. + +```typescript +// in cypress/support/index.d.ts +// load type definitions that come with Cypress module +/// + +declare namespace Cypress { + interface Chainable { + /** + * Custom command to select DOM element by data-cy attribute. + * @example cy.dataCy('greeting') + */ + dataCy(value: string): Chainable + } +} +``` + +{% note info %} +A nice detailed JSDoc comment above the method type will be really appreciated by the users. +{% endnote %} + +If your specs are coded in TypeScript, you should include `cypress/support/index.d.ts` file with the rest of the source files. Even if your project is JavaScript-only, the JS specs can know about the new command by referencing the file using the special tripple slash `reference path` comment. + +```javascript +// from your cypress/integration/spec.js +/// +it('works', () => { + cy.visit('/') + // IntelliSense and TS compiler should not complain about unknown method + cy.dataCy('greeting') +}) +``` + +### Examples -You can find an example in the {% url "cypress-example-todomvc custom commands" https://github.com/cypress-io/cypress-example-todomvc#custom-commands %} repo. +- See {% url "Adding Custom Commands" https://github.com/cypress-io/cypress-example-recipes#fundamentals %} example recipe. +- You can find a simple example with custom commands written in TypeScript in {% url "omerose/cypress-support" https://github.com/omerose/cypress-support %} repo. +- Example project {% url "cypress-example-todomvc custom commands" https://github.com/cypress-io/cypress-example-todomvc#custom-commands %} uses custom commands to avoid boilerplate code. ## Types for custom assertions From 111bb5789b8ac51f649eaf070b913bae2434fa2a Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Wed, 24 Jul 2019 10:57:16 +0630 Subject: [PATCH 2/3] Minor updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - link to custom commands doc - link to ‘supportFile’, since location may be different - remove duplicate header in doc - Add JSDoc to textlint --- .textlintrc | 1 + source/guides/tooling/typescript-support.md | 21 ++++++++++++++------- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/.textlintrc b/.textlintrc index f8e121067d..060d892e1d 100644 --- a/.textlintrc +++ b/.textlintrc @@ -37,6 +37,7 @@ "JavaScript", "Jest", "jQuery", + "JSDoc", ["local[ ]?storage", "localStorage"], "Lodash", "minimatch", diff --git a/source/guides/tooling/typescript-support.md b/source/guides/tooling/typescript-support.md index f05ae61cc8..6dc820acfb 100644 --- a/source/guides/tooling/typescript-support.md +++ b/source/guides/tooling/typescript-support.md @@ -45,14 +45,18 @@ You can find an example of Jest and Cypress installed in the same project using ## Types for custom commands -When adding custom commands to the `cy` object, you can add their types to avoid TypeScript errors. For example if you add method `cy.dataCy` in `cypress/support/index.js` like this: +When adding {% url "custom commands" custom-commands %} to the `cy` object, you can manually add their types to avoid TypeScript errors. + +For example if you add the command `cy.dataCy` into your {% url "`supportFile`" configuration#Folders-Files %} like this: ```javascript // cypress/support/index.js -Cypress.Commands.add('dataCy', (value) => cy.get(`[data-cy=${value}]`)) +Cypress.Commands.add('dataCy', (value) => { + return cy.get(`[data-cy=${value}]`) +}) ``` -Then you can add the method `dataCy` to the global Cypress `Chainable` interface (so called because commands are chained together) by creating a file `cypress/support/index.d.ts`. +Then you can add the `dataCy` command to the global Cypress Chainable interface (so called because commands are chained together) by creating a new TypeScript definitions file beside your {% url "`supportFile`" configuration#Folders-Files %}, in this case at `cypress/support/index.d.ts`. ```typescript // in cypress/support/index.d.ts @@ -71,22 +75,25 @@ declare namespace Cypress { ``` {% note info %} -A nice detailed JSDoc comment above the method type will be really appreciated by the users. +A nice detailed JSDoc comment above the method type will be really appreciated by any users of your custom command. {% endnote %} -If your specs are coded in TypeScript, you should include `cypress/support/index.d.ts` file with the rest of the source files. Even if your project is JavaScript-only, the JS specs can know about the new command by referencing the file using the special tripple slash `reference path` comment. +If your specs files are in TypeScript, you should include the TypeScript definition file, `cypress/support/index.d.ts`, with the rest of the source files. + +Even if your project is JavaScript only, the JavaScript specs can know about the new command by referencing the file using the special tripple slash `reference path` comment. ```javascript // from your cypress/integration/spec.js /// it('works', () => { cy.visit('/') - // IntelliSense and TS compiler should not complain about unknown method + // IntelliSense and TS compiler should + // not complain about unknown method cy.dataCy('greeting') }) ``` -### Examples +### Examples: - See {% url "Adding Custom Commands" https://github.com/cypress-io/cypress-example-recipes#fundamentals %} example recipe. - You can find a simple example with custom commands written in TypeScript in {% url "omerose/cypress-support" https://github.com/omerose/cypress-support %} repo. From bc1ef0ffcbecd16f4d331e1e400608b5ff7f9972 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Wed, 24 Jul 2019 10:59:42 +0630 Subject: [PATCH 3/3] copy typescript support doc to ja/cn --- source/guides/tooling/typescript-support.md | 2 +- .../ja/guides/tooling/typescript-support.md | 54 +++++++++++++++++-- .../guides/tooling/typescript-support.md | 54 +++++++++++++++++-- 3 files changed, 103 insertions(+), 7 deletions(-) diff --git a/source/guides/tooling/typescript-support.md b/source/guides/tooling/typescript-support.md index 6dc820acfb..152ed26ba4 100644 --- a/source/guides/tooling/typescript-support.md +++ b/source/guides/tooling/typescript-support.md @@ -45,7 +45,7 @@ You can find an example of Jest and Cypress installed in the same project using ## Types for custom commands -When adding {% url "custom commands" custom-commands %} to the `cy` object, you can manually add their types to avoid TypeScript errors. +When adding {% url "custom commands" custom-commands %} to the `cy` object, you can manually add their types to avoid TypeScript errors. For example if you add the command `cy.dataCy` into your {% url "`supportFile`" configuration#Folders-Files %} like this: diff --git a/source/ja/guides/tooling/typescript-support.md b/source/ja/guides/tooling/typescript-support.md index 4777ef0a43..152ed26ba4 100644 --- a/source/ja/guides/tooling/typescript-support.md +++ b/source/ja/guides/tooling/typescript-support.md @@ -45,11 +45,59 @@ You can find an example of Jest and Cypress installed in the same project using ## Types for custom commands -When adding custom commands to the `cy` object, you can add their types to avoid TypeScript errors. You can find the simplest implementation of Cypress and TypeScript in this {% url "repo example here" https://github.com/omerose/cypress-support %}. +When adding {% url "custom commands" custom-commands %} to the `cy` object, you can manually add their types to avoid TypeScript errors. -## TODO MVC Example Repo +For example if you add the command `cy.dataCy` into your {% url "`supportFile`" configuration#Folders-Files %} like this: -You can find an example in the {% url "cypress-example-todomvc custom commands" https://github.com/cypress-io/cypress-example-todomvc#custom-commands %} repo. +```javascript +// cypress/support/index.js +Cypress.Commands.add('dataCy', (value) => { + return cy.get(`[data-cy=${value}]`) +}) +``` + +Then you can add the `dataCy` command to the global Cypress Chainable interface (so called because commands are chained together) by creating a new TypeScript definitions file beside your {% url "`supportFile`" configuration#Folders-Files %}, in this case at `cypress/support/index.d.ts`. + +```typescript +// in cypress/support/index.d.ts +// load type definitions that come with Cypress module +/// + +declare namespace Cypress { + interface Chainable { + /** + * Custom command to select DOM element by data-cy attribute. + * @example cy.dataCy('greeting') + */ + dataCy(value: string): Chainable + } +} +``` + +{% note info %} +A nice detailed JSDoc comment above the method type will be really appreciated by any users of your custom command. +{% endnote %} + +If your specs files are in TypeScript, you should include the TypeScript definition file, `cypress/support/index.d.ts`, with the rest of the source files. + +Even if your project is JavaScript only, the JavaScript specs can know about the new command by referencing the file using the special tripple slash `reference path` comment. + +```javascript +// from your cypress/integration/spec.js +/// +it('works', () => { + cy.visit('/') + // IntelliSense and TS compiler should + // not complain about unknown method + cy.dataCy('greeting') +}) +``` + +### Examples: + +- See {% url "Adding Custom Commands" https://github.com/cypress-io/cypress-example-recipes#fundamentals %} example recipe. +- You can find a simple example with custom commands written in TypeScript in {% url "omerose/cypress-support" https://github.com/omerose/cypress-support %} repo. +- Example project {% url "cypress-example-todomvc custom commands" https://github.com/cypress-io/cypress-example-todomvc#custom-commands %} uses custom commands to avoid boilerplate code. ## Types for custom assertions diff --git a/source/zh-cn/guides/tooling/typescript-support.md b/source/zh-cn/guides/tooling/typescript-support.md index 4da8e67e76..0a5e53a6ee 100644 --- a/source/zh-cn/guides/tooling/typescript-support.md +++ b/source/zh-cn/guides/tooling/typescript-support.md @@ -45,11 +45,59 @@ You can find an example of Jest and Cypress installed in the same project using ## Types for custom commands -When adding custom commands to the `cy` object, you can add their types to avoid TypeScript errors. You can find the simplest implementation of Cypress and TypeScript in this {% url "repo example here" https://github.com/omerose/cypress-support %}. +When adding {% url "custom commands" custom-commands %} to the `cy` object, you can manually add their types to avoid TypeScript errors. -## TODO MVC Example Repo +For example if you add the command `cy.dataCy` into your {% url "`supportFile`" configuration#Folders-Files %} like this: -You can find an example in the {% url "cypress-example-todomvc custom commands" https://github.com/cypress-io/cypress-example-todomvc#custom-commands %} repo. +```javascript +// cypress/support/index.js +Cypress.Commands.add('dataCy', (value) => { + return cy.get(`[data-cy=${value}]`) +}) +``` + +Then you can add the `dataCy` command to the global Cypress Chainable interface (so called because commands are chained together) by creating a new TypeScript definitions file beside your {% url "`supportFile`" configuration#Folders-Files %}, in this case at `cypress/support/index.d.ts`. + +```typescript +// in cypress/support/index.d.ts +// load type definitions that come with Cypress module +/// + +declare namespace Cypress { + interface Chainable { + /** + * Custom command to select DOM element by data-cy attribute. + * @example cy.dataCy('greeting') + */ + dataCy(value: string): Chainable + } +} +``` + +{% note info %} +A nice detailed JSDoc comment above the method type will be really appreciated by any users of your custom command. +{% endnote %} + +If your specs files are in TypeScript, you should include the TypeScript definition file, `cypress/support/index.d.ts`, with the rest of the source files. + +Even if your project is JavaScript only, the JavaScript specs can know about the new command by referencing the file using the special tripple slash `reference path` comment. + +```javascript +// from your cypress/integration/spec.js +/// +it('works', () => { + cy.visit('/') + // IntelliSense and TS compiler should + // not complain about unknown method + cy.dataCy('greeting') +}) +``` + +### Examples: + +- See {% url "Adding Custom Commands" https://github.com/cypress-io/cypress-example-recipes#fundamentals %} example recipe. +- You can find a simple example with custom commands written in TypeScript in {% url "omerose/cypress-support" https://github.com/omerose/cypress-support %} repo. +- Example project {% url "cypress-example-todomvc custom commands" https://github.com/cypress-io/cypress-example-todomvc#custom-commands %} uses custom commands to avoid boilerplate code. ## Types for custom assertions