From 23f89059268740a7a32451a46121d5da51ba3af8 Mon Sep 17 00:00:00 2001 From: ZorphDark Date: Tue, 26 May 2026 22:20:49 -0400 Subject: [PATCH 1/3] docs: update e2e-testing guide to include official cli integrations and other e2e frameworks --- .../references/e2e-testing.md | 100 +++++++++--------- 1 file changed, 49 insertions(+), 51 deletions(-) diff --git a/skills/dev-skills/angular-developer/references/e2e-testing.md b/skills/dev-skills/angular-developer/references/e2e-testing.md index 1677f6c9d529..037c7ad08989 100644 --- a/skills/dev-skills/angular-developer/references/e2e-testing.md +++ b/skills/dev-skills/angular-developer/references/e2e-testing.md @@ -1,66 +1,64 @@ # End-to-End (E2E) Testing -This project uses [Cypress](https://www.cypress.io/) for end-to-end (E2E) testing, which simulates real user interactions in a browser. The E2E tests are located primarily within the `devtools/` package. +## Set Up E2E Testing -## Running E2E Tests +Configure E2E testing in an Angular workspace using the `ng e2e` command. If no E2E target is configured in `angular.json`, running `ng e2e` prompts to choose one of the officially integrated frameworks. -The primary way to run E2E tests is through the `pnpm` script defined in the root `package.json`. - -1. **Build DevTools:** The E2E tests run against a built version of the devtools extension. You must build it first: +Add supported E2E frameworks to the project using `ng add`: +* **Cypress:** ```shell - pnpm -F ng-devtools-mcp build:dev + ng add @cypress/schematic + ``` +* **Playwright:** + ```shell + ng add playwright-ng-schematics + ``` +* **Nightwatch:** + ```shell + ng add @nightwatch/schematics + ``` +* **WebdriverIO:** + ```shell + ng add @wdio/schematics + ``` +* **Puppeteer:** + ```shell + ng add @puppeteer/ng-schematics ``` -2. **Run Cypress:** Use the `cy:open` or `cy:run` script: - - To open the interactive Cypress Test Runner: - ```shell - pnpm -F ng-devtools-mcp cy:open - ``` - - To run the tests headlessly in the terminal (ideal for CI): - ```shell - pnpm -F ng-devtools-mcp cy:run - ``` - -## Test Structure - -- **Configuration:** The main Cypress configuration is located at `devtools/cypress.json`. -- **Specs:** Test files (specs) are located in `devtools/cypress/integration/`. -- **Custom Commands:** Reusable custom commands and actions are defined in `devtools/cypress/support/`. - -### Example E2E Test Snippet - -A typical test might look like this: - -```typescript -// in devtools/cypress/integration/profiler.spec.ts +Run E2E tests: +```shell +ng e2e [project] [options] +``` -describe('Profiler', () => { - beforeEach(() => { - cy.visit('/?e2e-app'); - cy.wait(1000); - cy.get('ng-devtools-tabs').find('a').contains('Profiler').click(); - }); +### Builder Configuration + +E2E runners are configured under the `e2e` target of the application in `angular.json`: +```json +"e2e": { + "builder": "@cypress/schematic:cypress", + "options": { + "devServerTarget": "my-app:serve" + }, + "configurations": { + "production": { + "devServerTarget": "my-app:serve:production" + } + } +} +``` - it('should record and display profiling data', () => { - // Find the record button and click it - cy.get('button[aria-label="start-recording-button"]').click(); +## Creating a Custom E2E Builder - // Interact with the test application to generate profiling data - cy.get('body').find('#cards button').first().click(); - cy.wait(500); +For advanced runner integrations (e.g., wrapper execution with custom setup/teardown), implement a custom CLI builder following the [Angular CLI Builder Documentation](https://angular.dev/tools/cli/cli-builder#creating-a-builder). - // Stop recording - cy.get('button[aria-label="stop-recording-button"]').click(); +## Custom & Enterprise Testing Tools - // Assert that the flame graph is now visible - cy.get('ng-devtools-recording-timeline').find('canvas').should('be.visible'); - }); -}); -``` +For custom enterprise runners (e.g., Katalon Studio, TestCafe, Selenium), define execution commands in `package.json` scripts. -### Best Practices +## Best Practices -- **Use `data-` attributes:** Whenever possible, use `data-cy` or similar attributes for selecting elements to make tests more resilient to CSS or structural changes. -- **Custom Commands:** Encapsulate common sequences of actions into custom commands in the `support` directory to keep tests clean and readable. -- **Wait for Application State:** Use `cy.wait()` for arbitrary waits sparingly. Prefer to wait for specific UI elements to appear or for network requests to complete to avoid flaky tests. +* **Use Resilient Selectors:** Target dedicated attributes (`data-testid`, `data-cy`, or standard ARIA roles) rather than CSS classes or element tags. +* **Decouple Tests:** Assert against user-visible UI states, DOM elements, and behaviors rather than component internals or Angular-specific framework state. +* **Manage Asynchronous Behavior:** Use framework-provided waiting APIs (e.g., waiting for network responses or elements to become visible) instead of arbitrary timeouts/sleeps. From 550020e8ad8a1293839c005c5573ea41d3287ae4 Mon Sep 17 00:00:00 2001 From: ZorphDark Date: Wed, 27 May 2026 21:32:59 -0400 Subject: [PATCH 2/3] docs: update E2E skill with revised sections --- skills/dev-skills/angular-developer/SKILL.md | 2 +- .../angular-developer/references/e2e-testing.md | 13 ++++--------- 2 files changed, 5 insertions(+), 10 deletions(-) diff --git a/skills/dev-skills/angular-developer/SKILL.md b/skills/dev-skills/angular-developer/SKILL.md index f332e3e0878f..250a0f8effbc 100644 --- a/skills/dev-skills/angular-developer/SKILL.md +++ b/skills/dev-skills/angular-developer/SKILL.md @@ -119,7 +119,7 @@ When writing or updating tests, consult the following references based on the ta - **Fundamentals**: Best practices for unit testing (Vitest), async patterns, and `TestBed`. Read [testing-fundamentals.md](references/testing-fundamentals.md) - **Component Harnesses**: Standard patterns for robust component interaction. Read [component-harnesses.md](references/component-harnesses.md) - **Router Testing**: Using `RouterTestingHarness` for reliable navigation tests. Read [router-testing.md](references/router-testing.md) -- **End-to-End (E2E) Testing**: Best practices for E2E tests with Cypress. Read [e2e-testing.md](references/e2e-testing.md) +- **End-to-End (E2E) Testing**: Setting up and running E2E tests. Read [e2e-testing.md](references/e2e-testing.md) ## Tooling diff --git a/skills/dev-skills/angular-developer/references/e2e-testing.md b/skills/dev-skills/angular-developer/references/e2e-testing.md index 037c7ad08989..747b2143f54f 100644 --- a/skills/dev-skills/angular-developer/references/e2e-testing.md +++ b/skills/dev-skills/angular-developer/references/e2e-testing.md @@ -1,8 +1,9 @@ # End-to-End (E2E) Testing -## Set Up E2E Testing +> [!IMPORTANT] +> Only use the setup guidelines in this file if there is no existing E2E testing framework configured in the workspace, or if the user has explicitly requested to change or set up E2E testing. -Configure E2E testing in an Angular workspace using the `ng e2e` command. If no E2E target is configured in `angular.json`, running `ng e2e` prompts to choose one of the officially integrated frameworks. +## Setting Up and Running E2E Tests Add supported E2E frameworks to the project using `ng add`: @@ -55,10 +56,4 @@ For advanced runner integrations (e.g., wrapper execution with custom setup/tear ## Custom & Enterprise Testing Tools -For custom enterprise runners (e.g., Katalon Studio, TestCafe, Selenium), define execution commands in `package.json` scripts. - -## Best Practices - -* **Use Resilient Selectors:** Target dedicated attributes (`data-testid`, `data-cy`, or standard ARIA roles) rather than CSS classes or element tags. -* **Decouple Tests:** Assert against user-visible UI states, DOM elements, and behaviors rather than component internals or Angular-specific framework state. -* **Manage Asynchronous Behavior:** Use framework-provided waiting APIs (e.g., waiting for network responses or elements to become visible) instead of arbitrary timeouts/sleeps. +For custom enterprise runners (e.g., Katalon Studio, TestCafe, Selenium), define execution commands in `package.json` scripts. \ No newline at end of file From 340ca3644898a765f6d5ba8a403e051be7041868 Mon Sep 17 00:00:00 2001 From: ZorphDark Date: Thu, 28 May 2026 13:48:17 -0400 Subject: [PATCH 3/3] docs: moved Playwright entry to the top of E2E skills suggestion --- .../angular-developer/references/e2e-testing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/dev-skills/angular-developer/references/e2e-testing.md b/skills/dev-skills/angular-developer/references/e2e-testing.md index 747b2143f54f..37b2029ff69b 100644 --- a/skills/dev-skills/angular-developer/references/e2e-testing.md +++ b/skills/dev-skills/angular-developer/references/e2e-testing.md @@ -7,14 +7,14 @@ Add supported E2E frameworks to the project using `ng add`: -* **Cypress:** - ```shell - ng add @cypress/schematic - ``` * **Playwright:** ```shell ng add playwright-ng-schematics ``` +* **Cypress:** + ```shell + ng add @cypress/schematic + ``` * **Nightwatch:** ```shell ng add @nightwatch/schematics