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

@@ -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\": \"<path-to-project-root>/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.",

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\": \"<path-to-project-root>/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",

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.

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": "<path-to-project-root>/cypress.config.ts",
+        "testingType": "component",
+        "devServerTarget": "some-angular-app:build",
+        "skipServe": true
+      }
+    }
+  }
+}
+```
+
+Nx also supports [React component testing](/packages/angular/generators/cypress-component-configuration).

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"
 }

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"
 }

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.