miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs(testing): add playwright overview page (#18357)

Browse Source
This commit is contained in:
Caleb Ukle 2023-08-02 10:07:01 -05:00 committed by GitHub
parent 5be931cd53
commit b5305604cd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 477 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/generated/manifests/menus.json
View File

@ -6939,6 +6939,23 @@
"path": "/packages/playwright",
"name": "playwright",
"children": [
{
"id": "documents",
"path": "/packages/playwright/documents",
"name": "documents",
"children": [
{
"name": "Overview",
"path": "/packages/playwright/documents/overview",
"id": "overview",
"isExternal": false,
"children": [],
"disableCollapsible": false
}
],
"isExternal": false,
"disableCollapsible": false
},
{
"id": "executors",
"path": "/packages/playwright/executors",

14
docs/generated/manifests/packages.json
View File

@ -1838,7 +1838,19 @@
"name": "playwright",
"packageName": "@nx/playwright",
"description": "The Nx Plugin for Playwright contains executors and generators allowing your workspace to use the powerful Playwright integration testing capabilities.",
"documents": {},
"documents": {
"/packages/playwright/documents/overview": {
"id": "overview",
"name": "Overview",
"description": "The Nx Plugin for Playwright contains executors and generators allowing your workspace to use the powerful Playwright integration testing capabilities.",
"file": "generated/packages/playwright/documents/overview",
"itemList": [],
"isExternal": false,
"path": "/packages/playwright/documents/overview",
"tags": [],
"originalFilePath": "shared/packages/playwright/playwright-plugin"
}
},
"root": "/packages/playwright",
"source": "/packages/playwright/src",
"executors": {

14
docs/generated/packages-metadata.json
View File

@ -1818,7 +1818,19 @@
},
{
"description": "The Nx Plugin for Playwright contains executors and generators allowing your workspace to use the powerful Playwright integration testing capabilities.",
"documents": [],
"documents": [
{
"id": "overview",
"name": "Overview",
"description": "The Nx Plugin for Playwright contains executors and generators allowing your workspace to use the powerful Playwright integration testing capabilities.",
"file": "generated/packages/playwright/documents/overview",
"itemList": [],
"isExternal": false,
"path": "playwright/documents/overview",
"tags": [],
"originalFilePath": "shared/packages/playwright/playwright-plugin"
}
],
"executors": [
{
"description": "Run Playwright tests.",

209
docs/generated/packages/playwright/documents/overview.md Normal file
View File

@ -0,0 +1,209 @@
Playwright is a modern web test runner. With included features such as:
- Cross browser support, including mobile browsers
- Multi tab, origin, and user support
- Automatic waiting
- Test generation
- Screenshots and videos
## Setting Up Playwright
If the `@nx/playwright` package is not installed, install the version that matches your `nx` package version.
{% tabs %}
{% tab label="npm" %}
```shell
npm install --save-dev @nx/playwright
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add --dev @nx/playwright
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm i -D @nx/playwright
```
{% /tab %}
{% /tabs %}
## E2E Testing
By default, when creating a new frontend application, Nx will prompt for which e2e test runner to use. Select `playwright` or pass in the arg `--e2eTestRunner=playwright`
```shell
nx g @nx/web:app frontend --e2eTestRunner=playwright
```
### Add Playwright e2e to an existing project
To generate an E2E project for an existing project, run the following generator
```shell
nx g @nx/playwright:configuration --project=your-app-name --project=your-app-name
```
Optionally, you can use the `--webServerCommand` and `--webServerAddress` option, to auto setup the [web server option](https://playwright.dev/docs/test-webserver) in the playwright config
```shell
nx g @nx/playwright:configuration --project=your-app-name --webServerCommand="npx serve your-project-name" --webServerAddress="http://localhost:4200"
```
### Testing Applications
Run `nx e2e <your-app-name>` to execute e2e tests with Playwright
{% callout type="note" title="Selecting Specific Specs" %}
You can use the `--grep/-g` flag to glob for test files.
You can use the `--grepInvert/-gv` flag to glob for files to _not_ run.
```bash
# run the tests in the feat-a/ directory
nx e2e frontend-e2e --grep="**feat-a/**"
# run everything except feat-a/ directory
nx e2e frontend-e2e --grepInvert=**feat-a/**
```
{% /callout %}
By default, Playwright will run in headless mode. You will have the result of all the tests and errors (if any) in your
terminal. Test output such as reports, screenshots and videos, will be accessible in `dist/.playwright/apps/<your-app-name>/`. This can be configured with the `outputDir` configuration options.
{% callout type="note" title="Output Caching" %}
If changing the output directory or report output, make sure to update the [target outputs](/concepts/how-caching-works#what-is-cached) so the artifacts are correctly cached
{% /callout %}
### Watching for Changes
With, `nx e2e frontend-e2e --ui` Playwright will start in headed mode where you can see your application being tested.
From, there you can toggle on the watch icon which will rerun the tests when the spec file updates.
```shell
nx e2e <your-app-name> --ui
```
You can also use `--headed` flag to run Playwright where the browser can be seen without using the [Playwright UI](https://playwright.dev/docs/test-ui-mode)
### Specifying a Base Url
The `baseURL` property within the Playwright configuration can control where the tests visit by default.
```ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
// Rest of your config...
// Run your local dev server before starting the tests
webServer: {
command: 'npx serve <your-app-name>',
url: 'http://localhost:4200',
reuseExistingServer: !process.env.CI,
},
use: {
baseURL: 'http://localhost:4200', // url playwright visits with `await page.goto('/')`;
},
});
```
In order to set different `baseURL` values for different environments you can pass them via the [environment variables and nx configurations](/recipes/tips-n-tricks/define-environment-variables) or optionally via setting them per the environment they are needed in such as `CI`
```ts
import { defineConfig } from '@playwright/test';
const baseUrl =
process.env.BASE_URL ?? process.env.CI
? 'https://some-staging-url.example.com'
: 'http://localhost:4200';
export default defineConfig({
// Rest of your config...
// Run your local dev server before starting the tests
webServer: {
command: 'npx serve <your-app-name>',
url: baseUrl,
reuseExistingServer: !process.env.CI,
},
use: {
baseURL: baseUrl, // url playwright visits with `await page.goto('/')`;
},
});
```
By default Nx, provides a `nxE2EPreset` with predefined configuration for Playwright.
```ts
import { defineConfig } from '@playwright/test';
import { nxE2EPreset } from '@nx/playwright/preset';
import { workspaceRoot } from '@nx/devkit';
// For CI, you may want to set BASE_URL to the deployed application.
const baseURL = process.env['BASE_URL'] || 'http://localhost:4200';
/**
* Read environment variables from file.
* https://github.com/motdotla/dotenv
*/
// require('dotenv').config();
/**
* See https://playwright.dev/docs/test-configuration.
*/
export default defineConfig({
...nxE2EPreset(__filename, { testDir: './e2e' }),
/* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
use: {
baseURL,
/* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
trace: 'on-first-retry',
},
/* Run your local dev server before starting the tests */
webServer: {
command: 'npx nx serve <your-app-name>',
url: baseURL,
reuseExistingServer: !process.env.CI,
cwd: workspaceRoot,
},
});
```
This preset sets up the `outputDir` and [HTML reporter](https://playwright.dev/docs/test-reporters#html-reporter) to output in `dist/.playwright/<path-to-project-root>` and sets up chromium, firefox, webkit browsers to be used a browser targets. If you want to use mobile and/or branded browsers you can pass those options into the preset function
```ts
export default defineConfig({
...nxE2EPreset(__filename, {
testDir: './e2e',
includeMobileBrowsers: true, // includes mobile Chrome and Safari
includeBrandedBrowsers: true, // includes Google Chrome and Microsoft Edge
}),
// other settings
});
```
If you want to override any settings within the `nxE2EPreset`, You can define them after the preset like so
```ts
const config = nxE2EPreset(__filename, {
testDir: './e2e',
includeMobileBrowsers: true, // includes mobile Chrome and Safari
includeBrandedBrowsers: true, // includes Google Chrome and Microsoft Edge
});
export default defineConfig({
...config
retries: 3,
reporters: [...config.reporters, /* other reporter settings */],
});
```
See the [Playwright configuration docs](https://playwright.dev/docs/test-configuration) for more options for Playwright.

14
docs/map.json
View File

@ -1926,6 +1926,20 @@
}
]
},
{
"name": "playwright",
"id": "playwright",
"description": "Playwright package.",
"itemList": [
{
"name": "Overview",
"id": "overview",
"path": "/packages/playwright",
"file": "shared/packages/playwright/playwright-plugin"
}
]
},
{
"name": "storybook",
"id": "storybook",

209
docs/shared/packages/playwright/playwright-plugin.md Normal file
View File

@ -0,0 +1,209 @@
Playwright is a modern web test runner. With included features such as:
- Cross browser support, including mobile browsers
- Multi tab, origin, and user support
- Automatic waiting
- Test generation
- Screenshots and videos
## Setting Up Playwright
If the `@nx/playwright` package is not installed, install the version that matches your `nx` package version.
{% tabs %}
{% tab label="npm" %}
```shell
npm install --save-dev @nx/playwright
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn add --dev @nx/playwright
```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm i -D @nx/playwright
```
{% /tab %}
{% /tabs %}
## E2E Testing
By default, when creating a new frontend application, Nx will prompt for which e2e test runner to use. Select `playwright` or pass in the arg `--e2eTestRunner=playwright`
```shell
nx g @nx/web:app frontend --e2eTestRunner=playwright
```
### Add Playwright e2e to an existing project
To generate an E2E project for an existing project, run the following generator
```shell
nx g @nx/playwright:configuration --project=your-app-name --project=your-app-name
```
Optionally, you can use the `--webServerCommand` and `--webServerAddress` option, to auto setup the [web server option](https://playwright.dev/docs/test-webserver) in the playwright config
```shell
nx g @nx/playwright:configuration --project=your-app-name --webServerCommand="npx serve your-project-name" --webServerAddress="http://localhost:4200"
```
### Testing Applications
Run `nx e2e <your-app-name>` to execute e2e tests with Playwright
{% callout type="note" title="Selecting Specific Specs" %}
You can use the `--grep/-g` flag to glob for test files.
You can use the `--grepInvert/-gv` flag to glob for files to _not_ run.
```bash
# run the tests in the feat-a/ directory
nx e2e frontend-e2e --grep="**feat-a/**"
# run everything except feat-a/ directory
nx e2e frontend-e2e --grepInvert=**feat-a/**
```
{% /callout %}
By default, Playwright will run in headless mode. You will have the result of all the tests and errors (if any) in your
terminal. Test output such as reports, screenshots and videos, will be accessible in `dist/.playwright/apps/<your-app-name>/`. This can be configured with the `outputDir` configuration options.
{% callout type="note" title="Output Caching" %}
If changing the output directory or report output, make sure to update the [target outputs](/concepts/how-caching-works#what-is-cached) so the artifacts are correctly cached
{% /callout %}
### Watching for Changes
With, `nx e2e frontend-e2e --ui` Playwright will start in headed mode where you can see your application being tested.
From, there you can toggle on the watch icon which will rerun the tests when the spec file updates.
```shell
nx e2e <your-app-name> --ui
```
You can also use `--headed` flag to run Playwright where the browser can be seen without using the [Playwright UI](https://playwright.dev/docs/test-ui-mode)
### Specifying a Base Url
The `baseURL` property within the Playwright configuration can control where the tests visit by default.
```ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
// Rest of your config...
// Run your local dev server before starting the tests
webServer: {
command: 'npx serve <your-app-name>',
url: 'http://localhost:4200',
reuseExistingServer: !process.env.CI,
},
use: {
baseURL: 'http://localhost:4200', // url playwright visits with `await page.goto('/')`;
},
});
```
In order to set different `baseURL` values for different environments you can pass them via the [environment variables and nx configurations](/recipes/tips-n-tricks/define-environment-variables) or optionally via setting them per the environment they are needed in such as `CI`
```ts
import { defineConfig } from '@playwright/test';
const baseUrl =
process.env.BASE_URL ?? process.env.CI
? 'https://some-staging-url.example.com'
: 'http://localhost:4200';
export default defineConfig({
// Rest of your config...
// Run your local dev server before starting the tests
webServer: {
command: 'npx serve <your-app-name>',
url: baseUrl,
reuseExistingServer: !process.env.CI,
},
use: {
baseURL: baseUrl, // url playwright visits with `await page.goto('/')`;
},
});
```
By default Nx, provides a `nxE2EPreset` with predefined configuration for Playwright.
```ts
import { defineConfig } from '@playwright/test';
import { nxE2EPreset } from '@nx/playwright/preset';
import { workspaceRoot } from '@nx/devkit';
// For CI, you may want to set BASE_URL to the deployed application.
const baseURL = process.env['BASE_URL'] || 'http://localhost:4200';
/**
* Read environment variables from file.
* https://github.com/motdotla/dotenv
*/
// require('dotenv').config();
/**
* See https://playwright.dev/docs/test-configuration.
*/
export default defineConfig({
...nxE2EPreset(__filename, { testDir: './e2e' }),
/* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
use: {
baseURL,
/* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
trace: 'on-first-retry',
},
/* Run your local dev server before starting the tests */
webServer: {
command: 'npx nx serve <your-app-name>',
url: baseURL,
reuseExistingServer: !process.env.CI,
cwd: workspaceRoot,
},
});
```
This preset sets up the `outputDir` and [HTML reporter](https://playwright.dev/docs/test-reporters#html-reporter) to output in `dist/.playwright/<path-to-project-root>` and sets up chromium, firefox, webkit browsers to be used a browser targets. If you want to use mobile and/or branded browsers you can pass those options into the preset function
```ts
export default defineConfig({
...nxE2EPreset(__filename, {
testDir: './e2e',
includeMobileBrowsers: true, // includes mobile Chrome and Safari
includeBrandedBrowsers: true, // includes Google Chrome and Microsoft Edge
}),
// other settings
});
```
If you want to override any settings within the `nxE2EPreset`, You can define them after the preset like so
```ts
const config = nxE2EPreset(__filename, {
testDir: './e2e',
includeMobileBrowsers: true, // includes mobile Chrome and Safari
includeBrandedBrowsers: true, // includes Google Chrome and Microsoft Edge
});
export default defineConfig({
...config
retries: 3,
reporters: [...config.reporters, /* other reporter settings */],
});
```
See the [Playwright configuration docs](https://playwright.dev/docs/test-configuration) for more options for Playwright.

2
docs/shared/reference/sitemap.md
View File

@ -487,6 +487,8 @@
- [run-commands](/packages/nx/executors/run-commands)
- [run-script](/packages/nx/executors/run-script)
- [playwright](/packages/playwright)
- [documents](/packages/playwright/documents)
- [Overview](/packages/playwright/documents/overview)
- [executors](/packages/playwright/executors)
- [playwright](/packages/playwright/executors/playwright)
- [generators](/packages/playwright/generators)