playwright-ng-schematics/README.md

Playwright Angular schematics

# Playwright Angular Schematic

[![NPM Version](https://img.shields.io/npm/v/playwright-ng-schematics)](https://www.npmjs.com/package/playwright-ng-schematics)
[![Playwright version](https://img.shields.io/npm/v/playwright?label=Playwright)](https://playwright.dev/)
[![Awesome](https://awesome.re/badge.svg)](https://github.com/mxschmitt/awesome-playwright)

Adds [Playwright Test](https://playwright.dev/) to your Angular project 

- Installs Playwright Test
- Set up `ng e2e` for you
- Adds configuration to `angular.json` for easy integration into your existing project
- `ng generate` e2e tests

<img src="docs/playwright-schematics.gif" alt="demo of ng e2e installing Playwright, then running end-to-end tests" width="800"/>

## Installation

Run the following to add Playwright to your Angular project. `ng add` will pick the correct version of this schematic automatically
```bash
ng add playwright-ng-schematics
```

Once installed, you can run the tests
```bash
npm run e2e
```

## Requirements

Angular 18+

## Usage

### Run tests

You can also use the Angular CLI `ng` to run your tests
```bash
ng e2e
```

You can use almost the same command-line interface options that exist for Playwright (see [Playwright Docs](https://playwright.dev/docs/test-cli) or use `ng e2e --help`), such as UI mode
```bash
ng e2e --ui
# or
npm run e2e -- --ui
```

To specify particular test files, usually done like this `npx playwright test tests/todo-page/ tests/landing-page/`, you have to prepend the `--files` argument.
```bash
ng e2e --files tests/todo-page/ --files tests/landing-page/
```
The `-c` option is used to choose an Angular configuration. If you also want to specify a Playwright configuration, use `--config` instead.

The `--project` option is used to choose an Angular project. If you want to specify a Playwright project, use `--test-project` instead.

### Start an Angular development server

If a `devServerTarget` option is specified, the builder will launch an Angular server and will automatically set the `PLAYWRIGHT_TEST_BASE_URL` environment variable.

```json title="angular.json"
        "e2e": {
          "builder": "playwright-ng-schematics:playwright",
          "options": {
            "devServerTarget": "my-app:serve",
            "ui": true
          },
          "configurations": {
            "production": {
              "devServerTarget": "my-app:serve:production"
            }
          }
        }
```

You can additionaly override the `port` of the dev server. It's handy when you want to run dev server and Playwright tests on different ports.
```json title="angular.json"
        "e2e": {
          "builder": "playwright-ng-schematics:playwright",
          "options": {
            "devServerTarget": "my-app:serve",
            "port": 0
          }
        }
```

You still can make use of Playwright's `baseURL` option and mix it with `PLAYWRIGHT_TEST_BASE_URL` env variable.  
The example below shows projects using `PLAYWRIGHT_TEST_BASE_URL` (set by `devServerTarget`) or another base URL.

```ts title="playwright.config.ts"
  // ...
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'], baseURL: process.env['PLAYWRIGHT_TEST_BASE_URL'] },
    },

    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'], baseURL: 'http://example.com' },
    },
  ]
```

### Create a test file

Create a new empty test
```bash
ng generate e2e "<TestName>"
```

or with CLI prompt of the name
```bash
ng generate e2e
```

## Migrating from Protractor

Still using Protractor ?

Read the [Migrating from Protractor](https://playwright.dev/docs/protractor) guide on the official Playwright website.

## Contributing

TL;DR
- Small, incremental changes are easier to review.
- Conventional Commits. NO EMOJI
- AI contributions are not encouraged.

---

If you want to initiate a big change, please create an issue first to discuss it. Keep your changes small (KISS).

Please stick to following conventions :
- Commit messages should follow the [Semantic Commit Messages](https://www.conventionalcommits.org/en/v1.0.0/) format. 
- Format (with Biome) and lint
- Write a useful test when applicable. We can pair if you need help on this !

I quite like this part from Playwright's CONTRIBUTING.md
> Low-Quality AI Contributions: PRs that do not meet our quality standards or lack human oversight (including low-quality agentic submissions) will be closed without explanation.

### Tips

The project uses [Biome](https://biomejs.dev/) for format and lint. You may use `npm run lint:fix` to format and auto-fixes.

To test, run
```bash
npm run build && npm test
```

A great way to run the schematics is to use npm link. Means `npm link` this project, then run `npm link playwright-ng-schematics` on the target.

You can run a specific version of Angular CLI as bellow.
```bash
npx @angular/cli@18 e2e
```

npm publication is performed in CI. np is quite useful for everything else (bumping version, perform checks, prepare the release).
```bash
npx np --no-publish
```

## License

This project is licensed under an Apache-2.0 license.