Skip to content

Commit d464695

Browse files
ismcagdasismcagdas
committed
Merge branch 'dev'
2 parents ff5319e + 0b76dee commit d464695

File tree

2 files changed

+110
-118
lines changed

2 files changed

+110
-118
lines changed

‎docs/en/Playwright-UI-Testing-Angular.md

Lines changed: 55 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,61 @@
1-
# Aspnet Zero UI Tests
1+
# UI Tests
22

3-
AspNet Zero provides an infrastructure for UI tests. It employs browser automation, screenshots, and image comparison to do so.
3+
ASP.NET Zero provides an infrastructure for UI tests using [Playwright](https://playwright.dev/). You can check Playwright documentation to learn more about its features.
44

55
## Project Setup & Structure
66

77
You should have the following installed in your system:
88

99
- [Node.js](https://nodejs.org/en/) is the runtime. Please make sure you have v12+ (LTS recommended) in your system before you start.
10-
- [npm] is the package manager and will help you install your dependencies and run scripts. It will be available when you install Node.js in your system.
10+
- [Yarn v1.x](https://classic.yarnpkg.com/lang/en/)
1111

1212
After making sure these exist in your system, follow the steps below:
1313

1414
1. Open your terminal.
15-
2. Navigate to the root folder of this project (if not already there).
16-
3. Run `npm install`.
17-
18-
The following dependencies will be installed:
19-
20-
- [TypeScript](https://github.com/microsoft/TypeScript) is the language we use in this project. All utilities, spec files, and extensions to Jest are in TypeScript.
21-
- [ES Lint](https://github.com/eslint/eslint) is the JavaScript/TypeScript linter. It finds and fixes problems in your code and thus ensures code quality and consistency.
22-
- [Prettier](https://github.com/prettier/prettier) formats your code. The current configuration in this project makes Prettier play well with ES Lint.
23-
- [dotenv](https://github.com/motdotla/dotenv) loads environment variables from the `.env` file.
24-
- [Jest](https://github.com/facebook/jest) is the testing framework. Jest is also a test runner, so you do not need a separate one. It also is highly extensible. This project benefits from the extensibility of Jest a lot.
25-
- [Playwright](https://github.com/microsoft/playwright) provides browser automation and screenshots. Playwright has a CLI which lets us generate the test code without writing (almost) any.
26-
- [Pixelmatch](https://github.com/mapbox/pixelmatch) compares screenshots. It takes two images and returns an image and a numeric value representing the difference (a.k.a. diff).
27-
- [pngjs](https://github.com/lukeapage/pngjs) is a PNG utility. It reads the PNG screenshots and materializes (writes) the diff as a PNG file.
28-
- [EJS](https://github.com/mde/ejs) is a simple JavaScript template engine. It renders the issue template based on given variables.
29-
- [fs-extra](https://github.com/jprichardson/node-fs-extra) provides promise-based file system methods. It reads, writes, and deletes files with great ease.
30-
- [Lodash](https://github.com/lodash/lodash) is a utility library for JavaScript. It provides methods to help you work with strings, arrays, objects, and more.
31-
- [Simple Git](https://github.com/steveukx/git-js) is a Node.js wrapper around git commands. We use it to create local branches, commit changes, and push commits to the remote.
32-
- [Octokit](https://github.com/octokit/rest.js) is the SDK of GitHub. We create issues and pull requests with it.
15+
2. Navigate to the `ui-tests-playwright` folder of this project.
16+
3. Run `yarn`.
3317

3418
There are two parts of the project that requires your close attention.
3519

36-
- The `jest.config.js` and the files under the `jest` folder establish the base for testing. You are not expected to make any changes to these files.
20+
- The `playwright.config.ts` is the configuration file for Playwright. You can check [https://playwright.dev/docs/test-configuration](https://playwright.dev/docs/test-configuration) to learn its options.
3721
- The `tests` folder includes the actual tests and utilities to create them with less effort. **This is where you will place your test suites.**
3822

39-
Another important file you need to know about is the `.env` file. This file contains project configuration. It does not exist in the repo for security reasons. Please find the `.env.example` file and create a local `.env` file based on the descriptions. You will need a GitHub personal access token. Please refer to [the GitHub documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) for details.
23+
Another important file you need to know about is the `.env` file. This file contains website URL to test, a username and a password to login.
4024

41-
After installing dependencies and creating a valid `.env` file, the project will be ready-to-run.
25+
After installing dependencies, the project will be ready-to-run.
4226

43-
## Running Tests in Development Mode
27+
### Ruuning the tests
4428

45-
Before you start, make sure your frontend and backend projects are running.
29+
Before running the UI tests, be sure that your Host and Angular apps are running with a brand new database.
4630

47-
The following steps take place upon running `npm test` in terminal:
31+
When you run the UI tests, a screenshot will be created for each UI test and this screenshot will be compared to new ones for the following executions of the same UI test.
4832

49-
1. The `jest` folder gets compiled.
50-
2. Jest starts based on the configurations in `jest.config.js`.
51-
3. All `.spec.ts` files in the `tests` folder get tested.
52-
4. Any changes to screenshots are saved.
53-
54-
However, this command runs all tests, and you will most likely want to run a single test most of the time. Insert the relative file path to the end of the same command for that.
33+
Because of that, if you are running the UI tests for the first time, you must add `--update-snapshots` parameter to your test execution command.
5534

5635
```shell
57-
npm test angular/editions
36+
npx playwright test --update-snapshots
5837
```
5938

60-
If you want to run all specs for one project
39+
For the following executions, you need to run same command without `--update-snapshots` parameter;
6140

6241
```shell
63-
npm test angular
42+
npx playwright test
6443
```
6544

66-
## Running Tests in CI Mode
67-
68-
Before you start, make sure your frontend and backend projects are running.
69-
70-
The following steps take place upon running `npm run test:ci` in terminal:
71-
72-
1. Every step in the "Development Mode" happens.
73-
2. Changes on each project are committed to separate branches.
74-
3. Generated branches are pushed to the remote.
75-
4. A single issue (per project with change) is created on the original project repo. The `/jest/diff_report.md` file is the issue template.
76-
5. A pull request is created for each branch. The PR refers to the issue on the original project repo.
77-
78-
Please note that this command creates actual commits, branches, issues, and pull requests. Therefore, you should run the "Development Mode" unless you want these to happen.
79-
80-
If you want the tests to run only for a single file, insert the relative file path to the end of the same command.
45+
This command runs all tests, but sometimes you may want to run a single test or a test group. For such cases, insert the relative file path to the end of the same command for that.
8146

8247
```shell
83-
npm run test:ci angular/editions
48+
npx playwright test angular/editions
8449
```
8550

86-
Using base project folder instead will run all specs for that particular project.
51+
If you want to run all specs for one project
8752

8853
```shell
89-
npm run test:ci angular
54+
npx playwright test angular
9055
```
9156

57+
In your own repository, you can store screenshots in your repository and this will allow you to easily run UI tests for your app.
58+
9259
## How to Create Tests
9360

9461
Please examine `tests/angular/editions.spec.ts` to see an example spec.
@@ -98,12 +65,41 @@ There are two ways to create a test.
9865
- Write directives to Playwright manually.
9966
- Use the Playwright CLI to generate code.
10067

101-
The first option requires you to know about the Playwright API. The second one, on the other hand, is quite easy. Please refer to [this section](https://github.com/microsoft/playwright-cli#generate-code) for details.
68+
ASP.NET Zero's default UI tests are executed in serial. So, tests are executed one by one and next test uses the state of previous test. We suggest using this approach when you are writing a UI test in your project as well.
69+
70+
Also, ASP.NET ZEro's default UI tests removes all data created during the UI tests. For example, this UI test creates a new Role with the name 'test' (Input fields are filled in a previous step which is not shown here).
71+
72+
````typescript
73+
/* Step 5 */
74+
test('should save record when "Save" button is clicked', async () => {
75+
await rolesPage.saveForm();
76+
await rolesPage.waitForResponse();
77+
await rolesPage.replaceLastColoumnOfTable();
78+
79+
await expect(page).toHaveScreenshot(ROLES_CRUD_NEW_SAVE);
80+
});
81+
````
82+
83+
And after that, this final step in Role UI test group removes the created record.
84+
85+
````typescript
86+
/* Step 12 */
87+
test('should delete record on click to "Yes" button', async () => {
88+
await rolesPage.openActionsDropdown(2);
89+
await rolesPage.waitForDropdownMenu();
90+
await rolesPage.triggerDropdownAction('Delete');
91+
await rolesPage.waitForConfirmationDialog();
92+
await rolesPage.confirmConfirmation();
93+
await rolesPage.waitForResponse();
94+
await rolesPage.replaceLastColoumnOfTable();
95+
96+
await expect(page).toHaveScreenshot(ROLES_CRUD_DELETE_CONFIRM);
97+
});
98+
````
10299

103-
Although Playwright CLI helps you create tests, you will notice that it sometimes produces element selectors that are too tied to implementation. Please refer to [the documentation for selectors](https://github.com/microsoft/playwright/blob/master/docs/selectors.md#element-selectors) to see different approaches you can take. Also, the example spec demonstrates how to use imported functions for reusable selectors.
100+
In this way, you can run your UI test during development.
104101

105-
**Tip:** If you want to run tests in debug mode, uncomment `DEBUG=pw:api` line in your `.env` file.
102+
**Tip:** If you want to see the browser when tests are running, set `headless: true` in **playwright.config.ts**.
106103

107-
**Tip:** If you want to see the browser when tests are running, uncomment `HEADFUL=` line in your `.env` file.
104+
**Tip:** If you use VSCode to write your tests you can use debugging.
108105

109-
**Tip:** If you use VSCode to write your tests you can use debugging.

‎docs/en/Playwright-UI-Testing.md

Lines changed: 55 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,61 @@
1-
# Aspnet Zero UI Tests
1+
# UI Tests
22

3-
AspNet Zero provides an infrastructure for UI tests. It employs browser automation, screenshots, and image comparison to do so.
3+
ASP.NET Zero provides an infrastructure for UI tests using [Playwright](https://playwright.dev/). You can check Playwright documentation to learn more about its features.
44

55
## Project Setup & Structure
66

77
You should have the following installed in your system:
88

99
- [Node.js](https://nodejs.org/en/) is the runtime. Please make sure you have v12+ (LTS recommended) in your system before you start.
10-
- [npm] is the package manager and will help you install your dependencies and run scripts. It will be available when you install Node.js in your system.
10+
- [Yarn v1.x](https://classic.yarnpkg.com/lang/en/)
1111

1212
After making sure these exist in your system, follow the steps below:
1313

1414
1. Open your terminal.
15-
2. Navigate to the root folder of this project (if not already there).
16-
3. Run `npm install`.
17-
18-
The following dependencies will be installed:
19-
20-
- [TypeScript](https://github.com/microsoft/TypeScript) is the language we use in this project. All utilities, spec files, and extensions to Jest are in TypeScript.
21-
- [ES Lint](https://github.com/eslint/eslint) is the JavaScript/TypeScript linter. It finds and fixes problems in your code and thus ensures code quality and consistency.
22-
- [Prettier](https://github.com/prettier/prettier) formats your code. The current configuration in this project makes Prettier play well with ES Lint.
23-
- [dotenv](https://github.com/motdotla/dotenv) loads environment variables from the `.env` file.
24-
- [Jest](https://github.com/facebook/jest) is the testing framework. Jest is also a test runner, so you do not need a separate one. It also is highly extensible. This project benefits from the extensibility of Jest a lot.
25-
- [Playwright](https://github.com/microsoft/playwright) provides browser automation and screenshots. Playwright has a CLI which lets us generate the test code without writing (almost) any.
26-
- [Pixelmatch](https://github.com/mapbox/pixelmatch) compares screenshots. It takes two images and returns an image and a numeric value representing the difference (a.k.a. diff).
27-
- [pngjs](https://github.com/lukeapage/pngjs) is a PNG utility. It reads the PNG screenshots and materializes (writes) the diff as a PNG file.
28-
- [EJS](https://github.com/mde/ejs) is a simple JavaScript template engine. It renders the issue template based on given variables.
29-
- [fs-extra](https://github.com/jprichardson/node-fs-extra) provides promise-based file system methods. It reads, writes, and deletes files with great ease.
30-
- [Lodash](https://github.com/lodash/lodash) is a utility library for JavaScript. It provides methods to help you work with strings, arrays, objects, and more.
31-
- [Simple Git](https://github.com/steveukx/git-js) is a Node.js wrapper around git commands. We use it to create local branches, commit changes, and push commits to the remote.
32-
- [Octokit](https://github.com/octokit/rest.js) is the SDK of GitHub. We create issues and pull requests with it.
15+
2. Navigate to the `ui-tests-playwright` folder of this project.
16+
3. Run `yarn`.
3317

3418
There are two parts of the project that requires your close attention.
3519

36-
- The `jest.config.js` and the files under the `jest` folder establish the base for testing. You are not expected to make any changes to these files.
20+
- The `playwright.config.ts` is the configuration file for Playwright. You can check [https://playwright.dev/docs/test-configuration](https://playwright.dev/docs/test-configuration) to learn its options.
3721
- The `tests` folder includes the actual tests and utilities to create them with less effort. **This is where you will place your test suites.**
3822

39-
Another important file you need to know about is the `.env` file. This file contains project configuration. It does not exist in the repo for security reasons. Please find the `.env.example` file and create a local `.env` file based on the descriptions. You will need a GitHub personal access token. Please refer to [the GitHub documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) for details.
23+
Another important file you need to know about is the `.env` file. This file contains website URL to test, a username and a password to login.
4024

41-
After installing dependencies and creating a valid `.env` file, the project will be ready-to-run.
25+
After installing dependencies, the project will be ready-to-run.
4226

43-
## Running Tests in Development Mode
27+
### Running the tests
4428

45-
Before you start, make sure your frontend and backend projects are running.
29+
Before running the UI tests, be sure that your MVC app is running with a brand new database.
4630

47-
The following steps take place upon running `npm test` in terminal:
31+
When you run the UI tests, a screenshot will be created for each UI test and this screenshot will be compared to new ones for the following executions of the same UI test.
4832

49-
1. The `jest` folder gets compiled.
50-
2. Jest starts based on the configurations in `jest.config.js`.
51-
3. All `.spec.ts` files in the `tests` folder get tested.
52-
4. Any changes to screenshots are saved.
53-
54-
However, this command runs all tests, and you will most likely want to run a single test most of the time. Insert the relative file path to the end of the same command for that.
33+
Because of that, if you are running the UI tests for the first time, you must add `--update-snapshots` parameter to your test execution command.
5534

5635
```shell
57-
npm test mvc/editions
36+
npx playwright test --update-snapshots
5837
```
5938

60-
If you want to run all specs for one project
39+
For the following executions, you need to run same command without `--update-snapshots` parameter;
6140

6241
```shell
63-
npm test mvc
42+
npx playwright test
6443
```
6544

66-
## Running Tests in CI Mode
67-
68-
Before you start, make sure your frontend and backend projects are running.
69-
70-
The following steps take place upon running `npm run test:ci` in terminal:
71-
72-
1. Every step in the "Development Mode" happens.
73-
2. Changes on each project are committed to separate branches.
74-
3. Generated branches are pushed to the remote.
75-
4. A single issue (per project with change) is created on the original project repo. The `/jest/diff_report.md` file is the issue template.
76-
5. A pull request is created for each branch. The PR refers to the issue on the original project repo.
77-
78-
Please note that this command creates actual commits, branches, issues, and pull requests. Therefore, you should run the "Development Mode" unless you want these to happen.
79-
80-
If you want the tests to run only for a single file, insert the relative file path to the end of the same command.
45+
This command runs all tests, but sometimes you may want to run a single test or a test group. For such cases, insert the relative file path to the end of the same command for that.
8146

8247
```shell
83-
npm run test:ci mvc/editions
48+
npx playwright test mvc/editions
8449
```
8550

86-
Using base project folder instead will run all specs for that particular project.
51+
If you want to run all specs for one project
8752

8853
```shell
89-
npm run test:ci mvc
54+
npx playwright test mvc
9055
```
9156

57+
In your own repository, you can store screenshots in your repository and this will allow you to easily run UI tests for your app.
58+
9259
## How to Create Tests
9360

9461
Please examine `tests/mvc/editions.spec.ts` to see an example spec.
@@ -98,12 +65,41 @@ There are two ways to create a test.
9865
- Write directives to Playwright manually.
9966
- Use the Playwright CLI to generate code.
10067

101-
The first option requires you to know about the Playwright API. The second one, on the other hand, is quite easy. Please refer to [this section](https://github.com/microsoft/playwright-cli#generate-code) for details.
68+
ASP.NET Zero's default UI tests are executed in serial. So, tests are executed one by one and next test uses the state of previous test. We suggest using this approach when you are writing a UI test in your project as well.
69+
70+
Also, ASP.NET ZEro's default UI tests removes all data created during the UI tests. For example, this UI test creates a new Role with the name 'test' (Input fields are filled in a previous step which is not shown here).
71+
72+
````typescript
73+
/* Step 5 */
74+
test('should save record when "Save" button is clicked', async () => {
75+
await rolesPage.saveForm();
76+
await rolesPage.waitForResponse();
77+
await rolesPage.replaceLastColoumnOfTable();
78+
79+
await expect(page).toHaveScreenshot(ROLES_CRUD_NEW_SAVE);
80+
});
81+
````
82+
83+
And after that, this final step in Role UI test group removes the created record.
84+
85+
````typescript
86+
/* Step 12 */
87+
test('should delete record on click to "Yes" button', async () => {
88+
await rolesPage.openActionsDropdown(2);
89+
await rolesPage.waitForDropdownMenu();
90+
await rolesPage.triggerDropdownAction('Delete');
91+
await rolesPage.waitForConfirmationDialog();
92+
await rolesPage.confirmConfirmation();
93+
await rolesPage.waitForResponse();
94+
await rolesPage.replaceLastColoumnOfTable();
95+
96+
await expect(page).toHaveScreenshot(ROLES_CRUD_DELETE_CONFIRM);
97+
});
98+
````
10299

103-
Although Playwright CLI helps you create tests, you will notice that it sometimes produces element selectors that are too tied to implementation. Please refer to [the documentation for selectors](https://github.com/microsoft/playwright/blob/master/docs/selectors.md#element-selectors) to see different approaches you can take. Also, the example spec demonstrates how to use imported functions for reusable selectors.
100+
In this way, you can run your UI test during development.
104101

105-
**Tip:** If you want to run tests in debug mode, uncomment `DEBUG=pw:api` line in your `.env` file.
102+
**Tip:** If you want to see the browser when tests are running, set `headless: true` in **playwright.config.ts**.
106103

107-
**Tip:** If you want to see the browser when tests are running, uncomment `HEADFUL=` line in your `.env` file.
104+
**Tip:** If you use VSCode to write your tests you can use debugging.
108105

109-
**Tip:** If you use VSCode to write your tests you can use debugging.

0 commit comments

Comments
 (0)