From b20c309466c6935c3483b27294396472e31fde0e Mon Sep 17 00:00:00 2001 From: Caleb Ukle Date: Wed, 19 Oct 2022 12:09:35 -0700 Subject: [PATCH] docs(testing): add docs for cypress ct in angular and react packages (#12629) * docs(react): add cypress component testing example files * docs(angular): add cypress component test example files --- docs/generated/packages/angular.json | 2 + docs/generated/packages/react.json | 2 + .../angular/docs/component-test-examples.md | 21 ++++ ...ypress-component-configuration-examples.md | 101 ++++++++++++++++++ .../src/generators/component-test/schema.json | 3 +- .../schema.json | 3 +- .../react/docs/component-test-examples.md | 22 ++++ ...ypress-component-configuration-examples.md | 100 +++++++++++++++++ .../src/generators/component-test/schema.json | 3 +- .../schema.json | 3 +- 10 files changed, 256 insertions(+), 4 deletions(-) create mode 100644 packages/angular/docs/component-test-examples.md create mode 100644 packages/angular/docs/cypress-component-configuration-examples.md create mode 100644 packages/react/docs/component-test-examples.md create mode 100644 packages/react/docs/cypress-component-configuration-examples.md diff --git a/docs/generated/packages/angular.json b/docs/generated/packages/angular.json index 4e4f3977d360d..fad415bbce13b 100644 --- a/docs/generated/packages/angular.json +++ b/docs/generated/packages/angular.json @@ -528,6 +528,7 @@ "componentDir", "componentFileName" ], + "examplesFile": "{% callout type=\"caution\" title=\"Can I use component testing?\" %}\nAngular component testing with Nx requires **Cypress version 10.7.0** and up.\n\nYou can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10).\n\nThis generator is for Cypress based component testing.\n\nIf you're wanting to create Cypress tests for a Storybook story, then check out the [component-cypress-spec generator docs](/packages/angular/generators/component-cypress-spec)\n\nIf you're wanting to create Storybook stories for a component, then check out the [stories generator docs](/packages/angular/generators/stories) or [component-story generator docs](/packages/angular/generators/component-cypress-spec)\n{% /callout %}\n\nThis generator is used to create a Cypress component test file for a given Angular component.\n\n```shell\nnx g @nrwl/angular:component-test --project=my-cool-angular-project --componentName=CoolBtnComponent --componentDir=src/cool-btn --componentFileName=cool-btn.component\n```\n\nTest file are generated with the `.cy.ts` suffix. this is to prevent colliding with any existing `.spec.` files contained in the project.\n\nIt's currently expected the generated `.cy.ts` file will live side by side with the component. It is also assumed the project is already setup for component testing. If it isn't, then you can run the [cypress-component-project generator](/packages/angular/generators/cypress-component-configuration) to set up the project for component testing.\n", "presets": [] }, "description": "Creates a cypress component test file for a component.", @@ -2299,6 +2300,7 @@ } }, "required": ["project"], + "examplesFile": "{% callout type=\"caution\" title=\"Can I use component testing?\" %}\nAngular component testing with Nx requires **Cypress version 10.7.0** and up.\n\nYou can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10).\n\nThis generator is for Cypress based component testing.\n\nIf you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/packages/angular/generators/storybook-configuration)\n{% /callout %}\n\nThis generator is designed to get your Angular project up and running with Cypress Component Testing.\n\n```shell\nnx g @nrwl/angular:cypress-component-project --project=my-cool-angular-project\n```\n\nRunning this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces.\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nrwl/angular/plugins/component-testing';\n\nexport default defineConfig({\n component: nxComponentTestingPreset(__filename),\n});\n```\n\nHere is an example on how to add custom options to the configuration\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nrwl/angular/plugins/component-testing';\n\nexport default defineConfig({\n component: {\n ...nxComponentTestingPreset(__filename),\n // extra options here\n },\n});\n```\n\n## Specifying a Build Target\n\nComponent testing requires a _build target_ to correctly run the component test dev server. This option can be manually specified with `--build-target=some-angular-app:build`, but Nx will infer this usage from the [project graph](/concepts/mental-model#the-project-graph) if one isn't provided.\n\nFor Angular projects, the build target needs to be using the `@nrwl/angular:webpack-browser` or\n`@angular-devkit/build-angular:browser` executor.\nThe generator will throw an error if a build target can't be found and suggest passing one in manually.\n\nLetting Nx infer the build target by default\n\n```shell\nnx g @nrwl/angular:cypress-component-project --project=my-cool-angular-project\n```\n\nManually specifying the build target\n\n```shell\nnx g @nrwl/angular:cypress-component-project --project=my-cool-angular-project --build-target:some-angular-app:build --generate-tests\n```\n\n{% callout type=\"note\" title=\"Build Target with Configuration\" %}\nIf you're wanting to use a build target with a specific configuration. i.e. `my-app:build:production`,\nthen manually providing `--build-target=my-app:build:production` is the best way to do that.\n{% /callout %}\n\n## Auto Generating Tests\n\nYou can optionally use the `--generate-tests` flag to generate a test file for each component in your project.\n\n```shell\nnx g @nrwl/angular:cypress-component-project --project=my-cool-angular-project --generate-tests\n```\n\n## Running Component Tests\n\nA new `component-test` target will be added to the specified project to run your component tests.\n\n```shell\nnx g component-test my-cool-angular-project\n```\n\nHere is an example of the project configuration that is generated. The `--build-target` option is added as the `devServerTarget` which can be changed as needed.\n\n```json {% fileName=\"project.json\" %}\n{\n \"targets\" {\n \"component-test\": {\n \"executor\": \"@nrwl/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"/cypress.config.ts\",\n \"testingType\": \"component\",\n \"devServerTarget\": \"some-angular-app:build\",\n \"skipServe\": true\n }\n }\n }\n}\n```\n\nNx also supports [React component testing](/packages/angular/generators/cypress-component-configuration).\n", "presets": [] }, "description": "Setup Cypress component testing for a project.", diff --git a/docs/generated/packages/react.json b/docs/generated/packages/react.json index bf00f7687753c..bc4b6bcd59abc 100644 --- a/docs/generated/packages/react.json +++ b/docs/generated/packages/react.json @@ -1255,6 +1255,7 @@ } }, "required": ["project"], + "examplesFile": "{% callout type=\"caution\" title=\"Can I use component testing?\" %}\nReact component testing with Nx requires **Cypress version 10.7.0** and up.\n\nYou can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10).\n\nThis generator is for Cypress based component testing.\n\nIf you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/packages/react/generators/storybook-configuration)\n{% /callout %}\n\nThis generator is designed to get your React project up and running with Cypress Component Testing.\n\n```shell\nnx g @nrwl/react:cypress-component-project --project=my-cool-react-project\n```\n\nRunning this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces.\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nrwl/react/plugins/component-testing';\n\nexport default defineConfig({\n component: nxComponentTestingPreset(__filename),\n});\n```\n\nHere is an example on how to add custom options to the configuration\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nrwl/react/plugins/component-testing';\n\nexport default defineConfig({\n component: {\n ...nxComponentTestingPreset(__filename),\n // extra options here\n },\n});\n```\n\n## Specifying a Build Target\n\nComponent testing requires a _build target_ to correctly run the component test dev server. This option can be manually specified with `--build-target=some-react-app:build`, but Nx will infer this usage from the [project graph](/concepts/mental-model#the-project-graph) if one isn't provided.\n\nFor React projects, the build target needs to be using the `@nrwl/webpack:webpack` executor.\nThe generator will throw an error if a build target can't be found and suggest passing one in manually.\n\nLetting Nx infer the build target by default\n\n```shell\nnx g @nrwl/react:cypress-component-project --project=my-cool-react-project\n```\n\nManually specifying the build target\n\n```shell\nnx g @nrwl/react:cypress-component-project --project=my-cool-react-project --build-target:some-react-app:build --generate-tests\n```\n\n{% callout type=\"note\" title=\"Build Target with Configuration\" %}\nIf you're wanting to use a build target with a specific configuration. i.e. `my-app:build:production`,\nthen manually providing `--build-target=my-app:build:production` is the best way to do that.\n{% /callout %}\n\n## Auto Generating Tests\n\nYou can optionally use the `--generate-tests` flag to generate a test file for each component in your project.\n\n```shell\nnx g @nrwl/react:cypress-component-project --project=my-cool-react-project --generate-tests\n```\n\n## Running Component Tests\n\nA new `component-test` target will be added to the specified project to run your component tests.\n\n```shell\nnx g component-test my-cool-react-project\n```\n\nHere is an example of the project configuration that is generated. The `--build-target` option is added as the `devServerTarget` which can be changed as needed.\n\n```json {% fileName=\"project.json\" %}\n{\n \"targets\" {\n \"component-test\": {\n \"executor\": \"@nrwl/cypress:cypress\",\n \"options\": {\n \"cypressConfig\": \"/cypress.config.ts\",\n \"testingType\": \"component\",\n \"devServerTarget\": \"some-react-app:build\",\n \"skipServe\": true\n }\n }\n }\n}\n```\n\nNx also supports [Angular component testing](/packages/angular/generators/cypress-component-configuration).\n", "presets": [] }, "description": "Setup Cypress component testing for a React project", @@ -1293,6 +1294,7 @@ } }, "required": ["project", "componentPath"], + "examplesFile": "{% callout type=\"caution\" title=\"Can I use component testing?\" %}\nReact component testing with Nx requires **Cypress version 10** and up.\n\nYou can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10).\n\nThis generator is for Cypress based component testing.\n\nIf you're wanting to create Cypress tests for a Storybook story, then check out the [component-cypress-spec generator docs](/packages/react/generators/component-cypress-spec)\n\nIf you're wanting to create Storybook stories for a component, then check out the [stories generator docs](/packages/react/generators/stories) or [component-story generator docs](/packages/react/generators/component-cypress-spec)\n\n{% /callout %}\n\nThis generator is used to create a Cypress component test file for a given React component.\n\n```shell\nnx g @nrwl/react:component-test --project=my-cool-react-project --componentPath=src/my-fancy-button.tsx\n```\n\nTest file are generated with the `.cy.` suffix. this is to prevent colliding with any existing `.spec.` files contained in the project.\n\nIt's currently expected the generated `.cy.` file will live side by side with the component. It is also assumed the project is already setup for component testing. If it isn't, then you can run the [cypress-component-project generator](/packages/react/generators/cypress-component-configuration) to set up the project for component testing.\n", "presets": [] }, "description": "Generate a Cypress component test for a React component", diff --git a/packages/angular/docs/component-test-examples.md b/packages/angular/docs/component-test-examples.md new file mode 100644 index 0000000000000..1bd6196767e5c --- /dev/null +++ b/packages/angular/docs/component-test-examples.md @@ -0,0 +1,21 @@ +{% callout type="caution" title="Can I use component testing?" %} +Angular component testing with Nx requires **Cypress version 10.7.0** and up. + +You can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10). + +This generator is for Cypress based component testing. + +If you're wanting to create Cypress tests for a Storybook story, then check out the [component-cypress-spec generator docs](/packages/angular/generators/component-cypress-spec) + +If you're wanting to create Storybook stories for a component, then check out the [stories generator docs](/packages/angular/generators/stories) or [component-story generator docs](/packages/angular/generators/component-cypress-spec) +{% /callout %} + +This generator is used to create a Cypress component test file for a given Angular component. + +```shell +nx g @nrwl/angular:component-test --project=my-cool-angular-project --componentName=CoolBtnComponent --componentDir=src/cool-btn --componentFileName=cool-btn.component +``` + +Test file are generated with the `.cy.ts` suffix. this is to prevent colliding with any existing `.spec.` files contained in the project. + +It's currently expected the generated `.cy.ts` file will live side by side with the component. It is also assumed the project is already setup for component testing. If it isn't, then you can run the [cypress-component-project generator](/packages/angular/generators/cypress-component-configuration) to set up the project for component testing. diff --git a/packages/angular/docs/cypress-component-configuration-examples.md b/packages/angular/docs/cypress-component-configuration-examples.md new file mode 100644 index 0000000000000..fb908c81eeaa6 --- /dev/null +++ b/packages/angular/docs/cypress-component-configuration-examples.md @@ -0,0 +1,101 @@ +{% callout type="caution" title="Can I use component testing?" %} +Angular component testing with Nx requires **Cypress version 10.7.0** and up. + +You can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10). + +This generator is for Cypress based component testing. + +If you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/packages/angular/generators/storybook-configuration) +{% /callout %} + +This generator is designed to get your Angular project up and running with Cypress Component Testing. + +```shell +nx g @nrwl/angular:cypress-component-project --project=my-cool-angular-project +``` + +Running this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces. + +```ts {% fileName="cypress.config.ts" %} +import { defineConfig } from 'cypress'; +import { nxComponentTestingPreset } from '@nrwl/angular/plugins/component-testing'; + +export default defineConfig({ + component: nxComponentTestingPreset(__filename), +}); +``` + +Here is an example on how to add custom options to the configuration + +```ts {% fileName="cypress.config.ts" %} +import { defineConfig } from 'cypress'; +import { nxComponentTestingPreset } from '@nrwl/angular/plugins/component-testing'; + +export default defineConfig({ + component: { + ...nxComponentTestingPreset(__filename), + // extra options here + }, +}); +``` + +## Specifying a Build Target + +Component testing requires a _build target_ to correctly run the component test dev server. This option can be manually specified with `--build-target=some-angular-app:build`, but Nx will infer this usage from the [project graph](/concepts/mental-model#the-project-graph) if one isn't provided. + +For Angular projects, the build target needs to be using the `@nrwl/angular:webpack-browser` or +`@angular-devkit/build-angular:browser` executor. +The generator will throw an error if a build target can't be found and suggest passing one in manually. + +Letting Nx infer the build target by default + +```shell +nx g @nrwl/angular:cypress-component-project --project=my-cool-angular-project +``` + +Manually specifying the build target + +```shell +nx g @nrwl/angular:cypress-component-project --project=my-cool-angular-project --build-target:some-angular-app:build --generate-tests +``` + +{% callout type="note" title="Build Target with Configuration" %} +If you're wanting to use a build target with a specific configuration. i.e. `my-app:build:production`, +then manually providing `--build-target=my-app:build:production` is the best way to do that. +{% /callout %} + +## Auto Generating Tests + +You can optionally use the `--generate-tests` flag to generate a test file for each component in your project. + +```shell +nx g @nrwl/angular:cypress-component-project --project=my-cool-angular-project --generate-tests +``` + +## Running Component Tests + +A new `component-test` target will be added to the specified project to run your component tests. + +```shell +nx g component-test my-cool-angular-project +``` + +Here is an example of the project configuration that is generated. The `--build-target` option is added as the `devServerTarget` which can be changed as needed. + +```json {% fileName="project.json" %} +{ + "targets" { + "component-test": { + "executor": "@nrwl/cypress:cypress", + "options": { + "cypressConfig": "/cypress.config.ts", + "testingType": "component", + "devServerTarget": "some-angular-app:build", + "skipServe": true + } + } + } +} +``` + +Nx also supports [React component testing](/packages/angular/generators/cypress-component-configuration). diff --git a/packages/angular/src/generators/component-test/schema.json b/packages/angular/src/generators/component-test/schema.json index b98cf64eff745..ffb7a5f314cad 100644 --- a/packages/angular/src/generators/component-test/schema.json +++ b/packages/angular/src/generators/component-test/schema.json @@ -36,5 +36,6 @@ } }, "additionalProperties": false, - "required": ["project", "componentName", "componentDir", "componentFileName"] + "required": ["project", "componentName", "componentDir", "componentFileName"], + "examplesFile": "../../../docs/component-test-examples.md" } diff --git a/packages/angular/src/generators/cypress-component-configuration/schema.json b/packages/angular/src/generators/cypress-component-configuration/schema.json index 8701b078a775e..a642d0b9e33eb 100644 --- a/packages/angular/src/generators/cypress-component-configuration/schema.json +++ b/packages/angular/src/generators/cypress-component-configuration/schema.json @@ -29,5 +29,6 @@ "default": false } }, - "required": ["project"] + "required": ["project"], + "examplesFile": "../../../docs/cypress-component-configuration-examples.md" } diff --git a/packages/react/docs/component-test-examples.md b/packages/react/docs/component-test-examples.md new file mode 100644 index 0000000000000..e775d3d48648d --- /dev/null +++ b/packages/react/docs/component-test-examples.md @@ -0,0 +1,22 @@ +{% callout type="caution" title="Can I use component testing?" %} +React component testing with Nx requires **Cypress version 10** and up. + +You can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10). + +This generator is for Cypress based component testing. + +If you're wanting to create Cypress tests for a Storybook story, then check out the [component-cypress-spec generator docs](/packages/react/generators/component-cypress-spec) + +If you're wanting to create Storybook stories for a component, then check out the [stories generator docs](/packages/react/generators/stories) or [component-story generator docs](/packages/react/generators/component-cypress-spec) + +{% /callout %} + +This generator is used to create a Cypress component test file for a given React component. + +```shell +nx g @nrwl/react:component-test --project=my-cool-react-project --componentPath=src/my-fancy-button.tsx +``` + +Test file are generated with the `.cy.` suffix. this is to prevent colliding with any existing `.spec.` files contained in the project. + +It's currently expected the generated `.cy.` file will live side by side with the component. It is also assumed the project is already setup for component testing. If it isn't, then you can run the [cypress-component-project generator](/packages/react/generators/cypress-component-configuration) to set up the project for component testing. diff --git a/packages/react/docs/cypress-component-configuration-examples.md b/packages/react/docs/cypress-component-configuration-examples.md new file mode 100644 index 0000000000000..d8a446c463c28 --- /dev/null +++ b/packages/react/docs/cypress-component-configuration-examples.md @@ -0,0 +1,100 @@ +{% callout type="caution" title="Can I use component testing?" %} +React component testing with Nx requires **Cypress version 10.7.0** and up. + +You can migrate with to v10 via the [migrate-to-cypress-10 generator](/packages/cypress/generators/migrate-to-cypress-10). + +This generator is for Cypress based component testing. + +If you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/packages/react/generators/storybook-configuration) +{% /callout %} + +This generator is designed to get your React project up and running with Cypress Component Testing. + +```shell +nx g @nrwl/react:cypress-component-project --project=my-cool-react-project +``` + +Running this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces. + +```ts {% fileName="cypress.config.ts" %} +import { defineConfig } from 'cypress'; +import { nxComponentTestingPreset } from '@nrwl/react/plugins/component-testing'; + +export default defineConfig({ + component: nxComponentTestingPreset(__filename), +}); +``` + +Here is an example on how to add custom options to the configuration + +```ts {% fileName="cypress.config.ts" %} +import { defineConfig } from 'cypress'; +import { nxComponentTestingPreset } from '@nrwl/react/plugins/component-testing'; + +export default defineConfig({ + component: { + ...nxComponentTestingPreset(__filename), + // extra options here + }, +}); +``` + +## Specifying a Build Target + +Component testing requires a _build target_ to correctly run the component test dev server. This option can be manually specified with `--build-target=some-react-app:build`, but Nx will infer this usage from the [project graph](/concepts/mental-model#the-project-graph) if one isn't provided. + +For React projects, the build target needs to be using the `@nrwl/webpack:webpack` executor. +The generator will throw an error if a build target can't be found and suggest passing one in manually. + +Letting Nx infer the build target by default + +```shell +nx g @nrwl/react:cypress-component-project --project=my-cool-react-project +``` + +Manually specifying the build target + +```shell +nx g @nrwl/react:cypress-component-project --project=my-cool-react-project --build-target:some-react-app:build --generate-tests +``` + +{% callout type="note" title="Build Target with Configuration" %} +If you're wanting to use a build target with a specific configuration. i.e. `my-app:build:production`, +then manually providing `--build-target=my-app:build:production` is the best way to do that. +{% /callout %} + +## Auto Generating Tests + +You can optionally use the `--generate-tests` flag to generate a test file for each component in your project. + +```shell +nx g @nrwl/react:cypress-component-project --project=my-cool-react-project --generate-tests +``` + +## Running Component Tests + +A new `component-test` target will be added to the specified project to run your component tests. + +```shell +nx g component-test my-cool-react-project +``` + +Here is an example of the project configuration that is generated. The `--build-target` option is added as the `devServerTarget` which can be changed as needed. + +```json {% fileName="project.json" %} +{ + "targets" { + "component-test": { + "executor": "@nrwl/cypress:cypress", + "options": { + "cypressConfig": "/cypress.config.ts", + "testingType": "component", + "devServerTarget": "some-react-app:build", + "skipServe": true + } + } + } +} +``` + +Nx also supports [Angular component testing](/packages/angular/generators/cypress-component-configuration). diff --git a/packages/react/src/generators/component-test/schema.json b/packages/react/src/generators/component-test/schema.json index bfaa00dbecc5d..0c71aaeab4d44 100644 --- a/packages/react/src/generators/component-test/schema.json +++ b/packages/react/src/generators/component-test/schema.json @@ -24,5 +24,6 @@ "x-prompt": "What is the path to the component?" } }, - "required": ["project", "componentPath"] + "required": ["project", "componentPath"], + "examplesFile": "../../../docs/component-test-examples.md" } diff --git a/packages/react/src/generators/cypress-component-configuration/schema.json b/packages/react/src/generators/cypress-component-configuration/schema.json index 90026d68fa39a..2764831b769ba 100644 --- a/packages/react/src/generators/cypress-component-configuration/schema.json +++ b/packages/react/src/generators/cypress-component-configuration/schema.json @@ -39,5 +39,6 @@ "default": false } }, - "required": ["project"] + "required": ["project"], + "examplesFile": "../../../docs/cypress-component-configuration-examples.md" }