From 4c7b29c4fc88df90aa3d71e131f2f44bd6040664 Mon Sep 17 00:00:00 2001 From: Caleb Ukle Date: Tue, 23 Sep 2025 10:55:38 -0500 Subject: [PATCH 1/4] docs(nx-dev): add playwright output merging guide --- .../test-tools/playwright/Guides/index.mdoc | 9 + .../Guides/merge-atomized-outputs.mdoc | 232 ++++++++++++++++++ 2 files changed, 241 insertions(+) create mode 100644 astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/index.mdoc create mode 100644 astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc diff --git a/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/index.mdoc b/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/index.mdoc new file mode 100644 index 00000000000000..a4a1de3c6727e0 --- /dev/null +++ b/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/index.mdoc @@ -0,0 +1,9 @@ +--- +title: Guides +sidebar: + hidden: true +description: Playwright configuration and usage +pagefind: false +--- + +{% index_page_cards path="technologies/test-tools/playwright/guides" /%} diff --git a/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc b/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc new file mode 100644 index 00000000000000..7c643906fb4cb0 --- /dev/null +++ b/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc @@ -0,0 +1,232 @@ +--- +title: Merge Atomized Playwright Outputs +sidebar: + label: Merge Atomized Outputs +filter: 'type:Guides' +--- + +When running Playwright tests in CI environments, Nx can [split tests across multiple parallel tasks](/docs/features/ci-features/split-e2e-tasks) for faster execution. +However, this creates separate test reports for each task. +With the Nx Plugin +The Playwright report merging feature allows you to combine these individual reports into a single, unified report. + +**Benefits:** + +- View all test results in one consolidated report +- Maintain the same reporting experience as non-atomized tests +- Keep the performance benefits of parallel test execution + +## Prerequisites + +- Nx workspace with `@nx/playwright` plugin +- Playwright tests configured in your project +- CI environment with [task atomization enabled](/docs/features/ci-features/split-e2e-tasks) +- Nx v21.6.1 + +{% aside type="note" title="Nx Version"%} +Nx v21.6.1 introduced automatic configuration of report merging which is the focus of this guide. +Similar steps can be followed for manual configuration of Playwright for any versions prior to Nx v21.6.1 +{%/aside%} + +## How report merging works + +1. **Blob Reports**: Playwright generates [lightweight "blob" reports](https://playwright.dev/docs/test-reporters#blob-reporter) during test execution +2. **Individual Tasks**: Each atomized test task creates its own blob report +3. **Report Merging**: A separate merge task combines all blob reports into unified output using your configured reporters (HTML, JSON, JUnit, etc.) + +## Configuration + +### Step 1: Enable blob reports + +The `nxE2EPreset` from `@nx/playwright/preset` automatically enable the blob reporter when running in CI: + +```ts +// playwright.config.ts +import { defineConfig } from '@playwright/test'; +import { nxE2EPreset } from '@nx/playwright/preset'; + +export default defineConfig({ + // automatically uses the blob reporter for CI + ...nxE2EPreset(__filename, { testDir: './src' }), + // Your additional configuration +}); +``` + +> The preset has a `generateBlobReports` option that can be used to disable the reporter or maybe enable it not just in CI. + +**Alternative manual configuration:** + +```ts +// playwright.config.ts +export default defineConfig({ + reporter: [ + ['html', { outputFolder: 'playwright-report' }], + ...(process.env.CI ? [['blob', { outputDir: 'blob-report' }]] : []) + ], + // Your other configuration +}); +``` + +### Step 2: Configure the playwright plugin + +Add a `ciTargetName` to the Playwright plugin to your `nx.json`. This will enable the report merging feature for CI environments: + +```json +// nx.json +{ + "plugins": [ + { + "plugin": "@nx/playwright/plugin", + "options": { + "targetName": "e2e", + "ciTargetName": "e2e-ci" + } + } + ] +} +``` + + +With the above configurations, Nx automatically creates these targets for your playwright projects: + +- `e2e`: Regular target for local development (runs all tests together) +- `e2e-ci`: CI target that runs tests in parallel across multiple tasks +- `e2e-ci-merge-reports`: Target that merges blob reports into unified reports + +## Running the feature + +**Local Development:** + +```shell {% frame="none" %} +# Run tests normally (no blob reports generated) +nx run my-app:e2e +``` + +**CI Environment:** + +```shell {% frame="none" %} +# Run atomized tests (generates blob reports) +nx run my-app:e2e-ci + +# Merge the reports +nx run my-app:e2e-ci-merge-reports +``` + +## Complete example + +Here's a complete working example for reference: + +```ts +// playwright.config.ts +import { defineConfig } from '@playwright/test'; +import { nxE2EPreset } from '@nx/playwright/preset'; + +export default defineConfig({ + ...nxE2EPreset(__filename, { testDir: './e2e' }), + use: { + baseURL: 'http://localhost:4200', + }, + webServer: { + command: 'npm run start', + port: 4200, + reuseExistingServer: !process.env.CI, + }, +}); +``` + +```json +// nx.json +{ + "plugins": [ + { + "plugin": "@nx/playwright/plugin", + "options": { + "targetName": "e2e", + "ciTargetName": "e2e-ci" + } + } + ] +} +``` + +## CI Integration + +> The following example CI configuration is for GitHub Actions, but the same steps can be followed in all CI providers. +> The most important part is to always call the merge report target, `e2e-ci-merge-reports`, even if the E2E tests fail to always have a final merged report. + +```yaml +// .github/workflows/ci.yaml +name: CI +on: + pull_request: + +jobs: + main: + steps: + ... + - name: Run E2E Tests + run: nx run my-app:e2e-ci + + - name: Merge Test Reports + run: nx run my-app:e2e-ci-merge-reports + # Run even if tests fail to get partial results + if: always() +``` + +## Troubleshooting + +### "The blob reporter is not configured" + +**Problem:** The merge task warns that no blob reporter is configured. + +**Solution:** Ensure the blob reporter is added to your Playwright configuration: + +- If overriding the `reporter` in the playwright configuration, make sure to add the blob reporter: + +```ts +// playwright.config.ts +export default defineConfig({ + reporter: [ + // existing reporters + ...(process.env.CI ? [['blob', { outputDir: 'blob-report' }]] : []) + ], + // Your other configuration +}); +``` + +### Missing test results in report + +**Problem:** The merge shows fewer results than expected test suites. + +**Solution:** + +- Check if some test tasks failed or were cancelled +- Verify all blob report files are present in the blob report directory +- Review CI logs for any task failures + +### Reports not merging + +**Problem:** Individual blob reports exist but aren't being merged. + +**Solution:** + +- Ensure the merge target is running after all test tasks complete + - The default merge target name is `e2e-ci-merge-reports` + - You can run `nx show project ` to view targets available on your project to verify the target exists +- Check that the blob report directory path is correct +- Verify Playwright CLI is available in the CI environment + +### [WARNING] "No additional reporters are configured" + +**Problem:** Only the blob reporter is configured, so it will be the only report produced + +**Solution:** Add at least one additional reporter (HTML, JSON, JUnit, etc.) alongside the blob reporter. + +List of available Playwright reports an be found in the [playwright documentation](https://playwright.dev/docs/test-reporters). + +## Best Practices + +1. **Environment-based Configuration**: Only enable blob reports in CI to avoid overhead during local development +2. **Error Handling**: Use `if: always()` (or similar) in CI workflows to merge partial results even when some tests fail +3. **Output Artifacts**: Archive both blob reports and merged reports as CI artifacts for debugging +4. **Validation**: The merge task automatically validates the expected number of test results From 5d1ce82f987f59dc78cbc6e29ee4b33649f9fd9c Mon Sep 17 00:00:00 2001 From: Caleb Ukle Date: Tue, 23 Sep 2025 13:31:13 -0500 Subject: [PATCH 2/4] docs(nx-dev): add playwright atomized merged output to nx.dev --- docs/generated/manifests/menus.json | 11 +- docs/generated/manifests/nx.json | 67 +++++- docs/map.json | 8 +- .../playwright/merge-atomized-outputs.md | 219 ++++++++++++++++++ docs/shared/reference/sitemap.md | 1 + 5 files changed, 300 insertions(+), 6 deletions(-) create mode 100644 docs/shared/packages/playwright/merge-atomized-outputs.md diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index c563860f76a390..053eb882d4177c 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -4682,7 +4682,16 @@ "path": "/technologies/test-tools/playwright/recipes", "id": "recipes", "isExternal": false, - "children": [], + "children": [ + { + "name": "Merge Atomized Outputs", + "path": "/technologies/test-tools/playwright/recipes/merge-atomized-outputs", + "id": "merge-atomized-outputs", + "isExternal": false, + "children": [], + "disableCollapsible": false + } + ], "disableCollapsible": false }, { diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index 2c5d475d017741..4da4ec09cfda9e 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -5259,7 +5259,19 @@ "description": "", "mediaImage": "", "file": "", - "itemList": [], + "itemList": [ + { + "id": "merge-atomized-outputs", + "name": "Merge Atomized Outputs", + "description": "", + "mediaImage": "", + "file": "shared/packages/playwright/merge-atomized-outputs", + "itemList": [], + "isExternal": false, + "path": "/technologies/test-tools/playwright/recipes/merge-atomized-outputs", + "tags": [] + } + ], "isExternal": false, "path": "/technologies/test-tools/playwright/recipes", "tags": [] @@ -10184,7 +10196,19 @@ "description": "", "mediaImage": "", "file": "", - "itemList": [], + "itemList": [ + { + "id": "merge-atomized-outputs", + "name": "Merge Atomized Outputs", + "description": "", + "mediaImage": "", + "file": "shared/packages/playwright/merge-atomized-outputs", + "itemList": [], + "isExternal": false, + "path": "/technologies/test-tools/playwright/recipes/merge-atomized-outputs", + "tags": [] + } + ], "isExternal": false, "path": "/technologies/test-tools/playwright/recipes", "tags": [] @@ -10747,7 +10771,19 @@ "description": "", "mediaImage": "", "file": "", - "itemList": [], + "itemList": [ + { + "id": "merge-atomized-outputs", + "name": "Merge Atomized Outputs", + "description": "", + "mediaImage": "", + "file": "shared/packages/playwright/merge-atomized-outputs", + "itemList": [], + "isExternal": false, + "path": "/technologies/test-tools/playwright/recipes/merge-atomized-outputs", + "tags": [] + } + ], "isExternal": false, "path": "/technologies/test-tools/playwright/recipes", "tags": [] @@ -10785,11 +10821,34 @@ "description": "", "mediaImage": "", "file": "", - "itemList": [], + "itemList": [ + { + "id": "merge-atomized-outputs", + "name": "Merge Atomized Outputs", + "description": "", + "mediaImage": "", + "file": "shared/packages/playwright/merge-atomized-outputs", + "itemList": [], + "isExternal": false, + "path": "/technologies/test-tools/playwright/recipes/merge-atomized-outputs", + "tags": [] + } + ], "isExternal": false, "path": "/technologies/test-tools/playwright/recipes", "tags": [] }, + "/technologies/test-tools/playwright/recipes/merge-atomized-outputs": { + "id": "merge-atomized-outputs", + "name": "Merge Atomized Outputs", + "description": "", + "mediaImage": "", + "file": "shared/packages/playwright/merge-atomized-outputs", + "itemList": [], + "isExternal": false, + "path": "/technologies/test-tools/playwright/recipes/merge-atomized-outputs", + "tags": [] + }, "/technologies/test-tools/playwright/api": { "id": "api", "name": "API", diff --git a/docs/map.json b/docs/map.json index 6f216a4be45dd3..beb53c40785a8f 100644 --- a/docs/map.json +++ b/docs/map.json @@ -1636,7 +1636,13 @@ { "name": "Guides", "id": "recipes", - "itemList": [] + "itemList": [ + { + "name": "Merge Atomized Outputs", + "id": "merge-atomized-outputs", + "file": "shared/packages/playwright/merge-atomized-outputs" + } + ] }, { "name": "API", diff --git a/docs/shared/packages/playwright/merge-atomized-outputs.md b/docs/shared/packages/playwright/merge-atomized-outputs.md new file mode 100644 index 00000000000000..c06b872c25f77a --- /dev/null +++ b/docs/shared/packages/playwright/merge-atomized-outputs.md @@ -0,0 +1,219 @@ +# Merge Atomized Playwright Outputs + +When running Playwright tests in CI environments, Nx can [split tests across multiple parallel tasks](/docs/features/ci-features/split-e2e-tasks) for faster execution. +However, this creates separate test reports for each task. +With the Nx Plugin +The Playwright report merging feature allows you to combine these individual reports into a single, unified report. + +**Benefits:** + +- View all test results in one consolidated report +- Maintain the same reporting experience as non-atomized tests +- Keep the performance benefits of parallel test execution + +## Prerequisites + +- Nx workspace with `@nx/playwright` plugin +- Playwright tests configured in your project +- CI environment with [task atomization enabled](/docs/features/ci-features/split-e2e-tasks) +- Nx v21.6.1 + +{% aside type="note" title="Nx Version"%} +Nx v21.6.1 introduced automatic configuration of report merging which is the focus of this guide. +Similar steps can be followed for manual configuration of Playwright for any versions prior to Nx v21.6.1 +{%/aside%} + +## How report merging works + +1. **Blob Reports**: Playwright generates [lightweight "blob" reports](https://playwright.dev/docs/test-reporters#blob-reporter) during test execution +2. **Individual Tasks**: Each atomized test task creates its own blob report +3. **Report Merging**: A separate merge task combines all blob reports into unified output using your configured reporters (HTML, JSON, JUnit, etc.) + +## Configuration + +### Step 1: Enable blob reports + +The `nxE2EPreset` from `@nx/playwright/preset` automatically enable the blob reporter when running in CI: + +```ts {% fileName="playwright.config.ts" %} +import { defineConfig } from '@playwright/test'; +import { nxE2EPreset } from '@nx/playwright/preset'; + +export default defineConfig({ + // automatically uses the blob reporter for CI + ...nxE2EPreset(__filename, { testDir: './src' }), + // Your additional configuration +}); +``` + +> The preset has a `generateBlobReports` option that can be used to disable the reporter or maybe enable it not just in CI. + +**Alternative manual configuration:** + +```ts {% fileName="playwright.config.ts" %} +export default defineConfig({ + reporter: [ + ['html', { outputFolder: 'playwright-report' }], + ...(process.env.CI ? [['blob', { outputDir: 'blob-report' }]] : []), + ], + // Your other configuration +}); +``` + +### Step 2: Configure the playwright plugin + +Add a `ciTargetName` to the Playwright plugin to your `nx.json`. This will enable the report merging feature for CI environments: + +```json {% fileName="nx.json" %} +{ + "plugins": [ + { + "plugin": "@nx/playwright/plugin", + "options": { + "targetName": "e2e", + "ciTargetName": "e2e-ci" + } + } + ] +} +``` + +With the above configurations, Nx automatically creates these targets for your playwright projects: + +- `e2e`: Regular target for local development (runs all tests together) +- `e2e-ci`: CI target that runs tests in parallel across multiple tasks +- `e2e-ci-merge-reports`: Target that merges blob reports into unified reports + +## Running the feature + +**Local Development:** + +```shell +# Run tests normally (no blob reports generated) +nx run my-app:e2e +``` + +**CI Environment:** + +```shell +# Run atomized tests (generates blob reports) +nx run my-app:e2e-ci + +# Merge the reports +nx run my-app:e2e-ci-merge-reports +``` + +## Complete example + +Here's a complete working example for reference: + +```ts {% fileName="playwright.config.ts" %} +import { defineConfig } from '@playwright/test'; +import { nxE2EPreset } from '@nx/playwright/preset'; + +export default defineConfig({ + ...nxE2EPreset(__filename, { testDir: './e2e' }), + use: { + baseURL: 'http://localhost:4200', + }, + webServer: { + command: 'npm run start', + port: 4200, + reuseExistingServer: !process.env.CI, + }, +}); +``` + +```json {% fileName="nx.json" %} +{ + "plugins": [ + { + "plugin": "@nx/playwright/plugin", + "options": { + "targetName": "e2e", + "ciTargetName": "e2e-ci" + } + } + ] +} +``` + +## CI Integration + +> The following example CI configuration is for GitHub Actions, but the same steps can be followed in all CI providers. +> The most important part is to always call the merge report target, `e2e-ci-merge-reports`, even if the E2E tests fail to always have a final merged report. + +```yaml {% fileName=".github/workflows/ci.yaml" %} +name: CI +on: + pull_request: + +jobs: + main: + steps: + ... + - name: Run E2E Tests + run: nx run my-app:e2e-ci + + - name: Merge Test Reports + run: nx run my-app:e2e-ci-merge-reports + # Run even if tests fail to get partial results + if: always() +``` + +## Troubleshooting + +### "The blob reporter is not configured" + +**Problem:** The merge task warns that no blob reporter is configured. + +**Solution:** Ensure the blob reporter is added to your Playwright configuration: + +- If overriding the `reporter` in the playwright configuration, make sure to add the blob reporter: + +```ts {% fileName="playwright.config.ts" %} +export default defineConfig({ + reporter: [ + // existing reporters + ...(process.env.CI ? [['blob', { outputDir: 'blob-report' }]] : []), + ], + // Your other configuration +}); +``` + +### Missing test results in report + +**Problem:** The merge shows fewer results than expected test suites. + +**Solution:** + +- Check if some test tasks failed or were cancelled +- Verify all blob report files are present in the blob report directory +- Review CI logs for any task failures + +### Reports not merging + +**Problem:** Individual blob reports exist but aren't being merged. + +**Solution:** + +- Ensure the merge target is running after all test tasks complete + - The default merge target name is `e2e-ci-merge-reports` + - You can run `nx show project ` to view targets available on your project to verify the target exists +- Check that the blob report directory path is correct +- Verify Playwright CLI is available in the CI environment + +### [WARNING] "No additional reporters are configured" + +**Problem:** Only the blob reporter is configured, so it will be the only report produced + +**Solution:** Add at least one additional reporter (HTML, JSON, JUnit, etc.) alongside the blob reporter. + +List of available Playwright reports an be found in the [playwright documentation](https://playwright.dev/docs/test-reporters). + +## Best Practices + +1. **Environment-based Configuration**: Only enable blob reports in CI to avoid overhead during local development +2. **Error Handling**: Use `if: always()` (or similar) in CI workflows to merge partial results even when some tests fail +3. **Output Artifacts**: Archive both blob reports and merged reports as CI artifacts for debugging +4. **Validation**: The merge task automatically validates the expected number of test results diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 3e51a84951c893..a23d032309450c 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -564,6 +564,7 @@ - [Playwright](/technologies/test-tools/playwright) - [Introduction](/technologies/test-tools/playwright/introduction) - [Guides](/technologies/test-tools/playwright/recipes) + - [Merge Atomized Outputs](/technologies/test-tools/playwright/recipes/merge-atomized-outputs) - [API](/technologies/test-tools/playwright/api) - [executors](/technologies/test-tools/playwright/api/executors) - [playwright](/technologies/test-tools/playwright/api/executors/playwright) From d53286c114be7480fc7d9b306862f5cc1a57039a Mon Sep 17 00:00:00 2001 From: Caleb Ukle Date: Tue, 23 Sep 2025 14:37:24 -0500 Subject: [PATCH 3/4] docs(nx-dev): apply PR feedback Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> --- .../test-tools/playwright/Guides/merge-atomized-outputs.mdoc | 5 ++--- docs/shared/packages/playwright/merge-atomized-outputs.md | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc b/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc index 7c643906fb4cb0..5182ac58713f59 100644 --- a/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc +++ b/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc @@ -7,8 +7,7 @@ filter: 'type:Guides' When running Playwright tests in CI environments, Nx can [split tests across multiple parallel tasks](/docs/features/ci-features/split-e2e-tasks) for faster execution. However, this creates separate test reports for each task. -With the Nx Plugin -The Playwright report merging feature allows you to combine these individual reports into a single, unified report. +With the Nx Plugin, the Playwright report merging feature allows you to combine these individual reports into a single, unified report. **Benefits:** @@ -222,7 +221,7 @@ export default defineConfig({ **Solution:** Add at least one additional reporter (HTML, JSON, JUnit, etc.) alongside the blob reporter. -List of available Playwright reports an be found in the [playwright documentation](https://playwright.dev/docs/test-reporters). +List of available Playwright reports can be found in the [playwright documentation](https://playwright.dev/docs/test-reporters). ## Best Practices diff --git a/docs/shared/packages/playwright/merge-atomized-outputs.md b/docs/shared/packages/playwright/merge-atomized-outputs.md index c06b872c25f77a..2310697eece4e7 100644 --- a/docs/shared/packages/playwright/merge-atomized-outputs.md +++ b/docs/shared/packages/playwright/merge-atomized-outputs.md @@ -2,8 +2,7 @@ When running Playwright tests in CI environments, Nx can [split tests across multiple parallel tasks](/docs/features/ci-features/split-e2e-tasks) for faster execution. However, this creates separate test reports for each task. -With the Nx Plugin -The Playwright report merging feature allows you to combine these individual reports into a single, unified report. +With the Nx Plugin, the Playwright report merging feature allows you to combine these individual reports into a single, unified report. **Benefits:** @@ -209,7 +208,7 @@ export default defineConfig({ **Solution:** Add at least one additional reporter (HTML, JSON, JUnit, etc.) alongside the blob reporter. -List of available Playwright reports an be found in the [playwright documentation](https://playwright.dev/docs/test-reporters). +List of available Playwright reports can be found in the [playwright documentation](https://playwright.dev/docs/test-reporters). ## Best Practices From 6d8e39d0eaa6f49db230b28f52d7fe06ebbd4531 Mon Sep 17 00:00:00 2001 From: Caleb Ukle Date: Tue, 23 Sep 2025 13:31:13 -0500 Subject: [PATCH 4/4] docs(nx-dev): add playwright atomized merged output to nx.dev --- .../Guides/merge-atomized-outputs.mdoc | 32 +++++++++--------- .../playwright/merge-atomized-outputs.md | 33 +++++++++++-------- 2 files changed, 35 insertions(+), 30 deletions(-) diff --git a/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc b/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc index 5182ac58713f59..e7279e34364fee 100644 --- a/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc +++ b/astro-docs/src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc @@ -1,5 +1,6 @@ --- title: Merge Atomized Playwright Outputs +description: Learn how to enable output merging for atomized Playwright tests sidebar: label: Merge Atomized Outputs filter: 'type:Guides' @@ -20,7 +21,7 @@ With the Nx Plugin, the Playwright report merging feature allows you to combine - Nx workspace with `@nx/playwright` plugin - Playwright tests configured in your project - CI environment with [task atomization enabled](/docs/features/ci-features/split-e2e-tasks) -- Nx v21.6.1 +- Nx v21.6.1 {% aside type="note" title="Nx Version"%} Nx v21.6.1 introduced automatic configuration of report merging which is the focus of this guide. @@ -60,15 +61,15 @@ export default defineConfig({ export default defineConfig({ reporter: [ ['html', { outputFolder: 'playwright-report' }], - ...(process.env.CI ? [['blob', { outputDir: 'blob-report' }]] : []) + ...(process.env.CI ? [['blob', { outputDir: 'blob-report' }]] : []), ], // Your other configuration }); ``` -### Step 2: Configure the playwright plugin +### Step 2: Configure the Playwright plugin -Add a `ciTargetName` to the Playwright plugin to your `nx.json`. This will enable the report merging feature for CI environments: +Add a `ciTargetName` to the Playwright plugin to your `nx.json`. This will enable task splitting and report merging features for CI environments: ```json // nx.json @@ -85,12 +86,11 @@ Add a `ciTargetName` to the Playwright plugin to your `nx.json`. This will enabl } ``` - -With the above configurations, Nx automatically creates these targets for your playwright projects: +With the above configurations, Nx automatically creates these targets for your Playwright projects: - `e2e`: Regular target for local development (runs all tests together) - `e2e-ci`: CI target that runs tests in parallel across multiple tasks -- `e2e-ci-merge-reports`: Target that merges blob reports into unified reports +- `e2e-ci--merge-reports`: Target that merges blob reports into unified reports ## Running the feature @@ -108,7 +108,7 @@ nx run my-app:e2e nx run my-app:e2e-ci # Merge the reports -nx run my-app:e2e-ci-merge-reports +nx run my-app:e2e-ci--merge-reports ``` ## Complete example @@ -151,7 +151,7 @@ export default defineConfig({ ## CI Integration > The following example CI configuration is for GitHub Actions, but the same steps can be followed in all CI providers. -> The most important part is to always call the merge report target, `e2e-ci-merge-reports`, even if the E2E tests fail to always have a final merged report. +> The most important part is to always call the merge report target, `e2e-ci--merge-reports`, even if the E2E tests fail to always have a final merged report. ```yaml // .github/workflows/ci.yaml @@ -167,9 +167,9 @@ jobs: run: nx run my-app:e2e-ci - name: Merge Test Reports - run: nx run my-app:e2e-ci-merge-reports + run: nx run my-app:e2e-ci--merge-reports # Run even if tests fail to get partial results - if: always() + if: always() ``` ## Troubleshooting @@ -180,14 +180,14 @@ jobs: **Solution:** Ensure the blob reporter is added to your Playwright configuration: -- If overriding the `reporter` in the playwright configuration, make sure to add the blob reporter: +- If overriding the `reporter` in the Playwright configuration, make sure to add the blob reporter: ```ts // playwright.config.ts export default defineConfig({ reporter: [ - // existing reporters - ...(process.env.CI ? [['blob', { outputDir: 'blob-report' }]] : []) + // existing reporters + ...(process.env.CI ? [['blob', { outputDir: 'blob-report' }]] : []), ], // Your other configuration }); @@ -210,7 +210,7 @@ export default defineConfig({ **Solution:** - Ensure the merge target is running after all test tasks complete - - The default merge target name is `e2e-ci-merge-reports` + - The default merge target name is `e2e-ci--merge-reports` - You can run `nx show project ` to view targets available on your project to verify the target exists - Check that the blob report directory path is correct - Verify Playwright CLI is available in the CI environment @@ -221,7 +221,7 @@ export default defineConfig({ **Solution:** Add at least one additional reporter (HTML, JSON, JUnit, etc.) alongside the blob reporter. -List of available Playwright reports can be found in the [playwright documentation](https://playwright.dev/docs/test-reporters). +List of available Playwright reports can be found in the [Playwright documentation](https://playwright.dev/docs/test-reporters). ## Best Practices diff --git a/docs/shared/packages/playwright/merge-atomized-outputs.md b/docs/shared/packages/playwright/merge-atomized-outputs.md index 2310697eece4e7..a7722be8b8f833 100644 --- a/docs/shared/packages/playwright/merge-atomized-outputs.md +++ b/docs/shared/packages/playwright/merge-atomized-outputs.md @@ -1,6 +1,11 @@ +--- +title: Merge Atomized Playwright Outputs +description: Learn how to enable output merging for atomized Playwright tests +--- + # Merge Atomized Playwright Outputs -When running Playwright tests in CI environments, Nx can [split tests across multiple parallel tasks](/docs/features/ci-features/split-e2e-tasks) for faster execution. +When running Playwright tests in CI environments, Nx can [split tests across multiple parallel tasks](/ci/features/split-e2e-tasks) for faster execution. However, this creates separate test reports for each task. With the Nx Plugin, the Playwright report merging feature allows you to combine these individual reports into a single, unified report. @@ -14,13 +19,13 @@ With the Nx Plugin, the Playwright report merging feature allows you to combine - Nx workspace with `@nx/playwright` plugin - Playwright tests configured in your project -- CI environment with [task atomization enabled](/docs/features/ci-features/split-e2e-tasks) +- CI environment with [task atomization enabled](/ci/features/split-e2e-tasks) - Nx v21.6.1 -{% aside type="note" title="Nx Version"%} +{% callout type="note" title="Nx Version"%} Nx v21.6.1 introduced automatic configuration of report merging which is the focus of this guide. Similar steps can be followed for manual configuration of Playwright for any versions prior to Nx v21.6.1 -{%/aside%} +{%/callout%} ## How report merging works @@ -59,9 +64,9 @@ export default defineConfig({ }); ``` -### Step 2: Configure the playwright plugin +### Step 2: Configure the Playwright plugin -Add a `ciTargetName` to the Playwright plugin to your `nx.json`. This will enable the report merging feature for CI environments: +Add a `ciTargetName` to the Playwright plugin to your `nx.json`. This will enable task splitting and report merging features for CI environments: ```json {% fileName="nx.json" %} { @@ -77,11 +82,11 @@ Add a `ciTargetName` to the Playwright plugin to your `nx.json`. This will enabl } ``` -With the above configurations, Nx automatically creates these targets for your playwright projects: +With the above configurations, Nx automatically creates these targets for your Playwright projects: - `e2e`: Regular target for local development (runs all tests together) - `e2e-ci`: CI target that runs tests in parallel across multiple tasks -- `e2e-ci-merge-reports`: Target that merges blob reports into unified reports +- `e2e-ci--merge-reports`: Target that merges blob reports into unified reports ## Running the feature @@ -99,7 +104,7 @@ nx run my-app:e2e nx run my-app:e2e-ci # Merge the reports -nx run my-app:e2e-ci-merge-reports +nx run my-app:e2e-ci--merge-reports ``` ## Complete example @@ -140,7 +145,7 @@ export default defineConfig({ ## CI Integration > The following example CI configuration is for GitHub Actions, but the same steps can be followed in all CI providers. -> The most important part is to always call the merge report target, `e2e-ci-merge-reports`, even if the E2E tests fail to always have a final merged report. +> The most important part is to always call the merge report target, `e2e-ci--merge-reports`, even if the E2E tests fail to always have a final merged report. ```yaml {% fileName=".github/workflows/ci.yaml" %} name: CI @@ -155,7 +160,7 @@ jobs: run: nx run my-app:e2e-ci - name: Merge Test Reports - run: nx run my-app:e2e-ci-merge-reports + run: nx run my-app:e2e-ci--merge-reports # Run even if tests fail to get partial results if: always() ``` @@ -168,7 +173,7 @@ jobs: **Solution:** Ensure the blob reporter is added to your Playwright configuration: -- If overriding the `reporter` in the playwright configuration, make sure to add the blob reporter: +- If overriding the `reporter` in the Playwright configuration, make sure to add the blob reporter: ```ts {% fileName="playwright.config.ts" %} export default defineConfig({ @@ -197,7 +202,7 @@ export default defineConfig({ **Solution:** - Ensure the merge target is running after all test tasks complete - - The default merge target name is `e2e-ci-merge-reports` + - The default merge target name is `e2e-ci--merge-reports` - You can run `nx show project ` to view targets available on your project to verify the target exists - Check that the blob report directory path is correct - Verify Playwright CLI is available in the CI environment @@ -208,7 +213,7 @@ export default defineConfig({ **Solution:** Add at least one additional reporter (HTML, JSON, JUnit, etc.) alongside the blob reporter. -List of available Playwright reports can be found in the [playwright documentation](https://playwright.dev/docs/test-reporters). +List of available Playwright reports can be found in the [Playwright documentation](https://playwright.dev/docs/test-reporters). ## Best Practices