You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+46-46Lines changed: 46 additions & 46 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,16 +2,12 @@
2
2
3
3
This package contains an end-to-end (E2E) testing suite for Magento 2, powered by [Playwright](https://playwright.dev/). It enables you to quickly set up, run, and extend automated browser tests for your Magento 2 store. Installation is simple via npm, allowing you to seamlessly integrate robust testing into your development workflow.
4
4
5
-
6
5
<mark>⚠️ Please note: if you’re not sure what each test does, **then you should only run this in a testing environment**! Some tests involve the database, and for the suite to run `setup.spec.ts` will disable the CATPCHA of your webshop.</mark>
7
6
8
-
9
7
🏃**Just want to install and get going?**
10
8
11
9
If you’re simply looking to install, check the [prerequisites](#prerequisites) and then go to [🧪 Installing the suite](#-installing-the-suite).
12
10
13
-
14
-
15
11
---
16
12
17
13
## Table of contents
@@ -35,8 +31,6 @@ If you’re simply looking to install, check the [prerequisites](#prerequisites)
35
31
* This testing suite has been designed to work within a Hÿva theme in Magento 2, but can work with other themes.
36
32
***Magento 2 instance:** A running instance of Magento 2 for testing purposes. Elgentos sponsors a [Hyvä demo website](https://hyva-demo.elgentos.io/) for this project.
37
33
38
-
39
-
40
34
---
41
35
42
36
## 🧪 Installing the suite
@@ -45,45 +39,34 @@ If you’re simply looking to install, check the [prerequisites](#prerequisites)
45
39
46
40
Navigate to the `web` folder of your theme. This is usually located in `app/design/frontend/{vendor}/{theme}/web`. Within this folder, create a `playwright` folder, then navigate to it:
47
41
48
-
49
42
```bash
50
43
cd app/design/frontend/demo-store/demo-theme/web
51
44
mkdir playwright
52
45
cd playwright
53
46
```
54
47
55
-
56
48
2.**Initialize an npm project:**
57
49
58
-
59
50
```bash
60
51
npm init -y
61
52
```
62
53
63
-
64
54
3.**Install the test suite package**
65
55
66
56
Lastly, simply run the command to install the elgentos Magento2 Playwright package, and the installation script will set things up for you! You will be prompted to input values for the `.env` variables, but these also come with default values.
67
57
68
-
69
58
```bash
70
59
npm install @elgentos/magento2-playwright
71
60
```
72
61
73
-
74
-
75
62
---
76
63
77
64
## ⏸️ Before you run
78
65
79
-
After the installation, a variety of folders will have been created. Most notable in these are `base-tests`, which contain the tests without alteration, and `tests`. **You should never make changes directly to the base-tests folder, as this may break functionality. However, note that the**`base-tests`**can be updated when you upgrade the package, so always review any changes after an update.**
80
-
81
-
66
+
After the installation, a variety of folders will have been created. Most notable in these are `base-tests`, which contain the tests without alteration, and `tests`. **You should never make changes directly to the base-tests folder, as thisx may break functionality. However, note that the**`base-tests`**can be updated when you upgrade the package, so always review any changes after an update.**
82
67
83
68
> If you want to make changes to your iteration of the testing suite such as making changes to how the test works, updating element identifiers etc., see the section ‘Customizing the testing suite’ below.
84
69
85
-
86
-
87
70
---
88
71
89
72
## 🤖 Run setup… then you can run the suite!
@@ -95,22 +78,18 @@ Finally, before running the testing suite, you must run `setup.spec.ts`. This mu
95
78
npx playwright test --grep "@setup" --trace on
96
79
```
97
80
98
-
99
81
After that - you’re all set! 🥳 You can run the testing suite - feel free to skip the setup at this point:
100
82
101
83
```bash
102
84
npx playrwight test --grep-invert "@setup" --trace on
103
85
```
104
86
105
-
106
-
107
87
---
108
88
109
89
## 🚀 How to use the testing suite
110
90
111
91
The Testing Suite offers a variety of tests for your Magento 2 application in Chromium, Firefox, and Webkit.
112
92
113
-
114
93
### Running tests
115
94
116
95
To run all tests, run the following command:
@@ -119,37 +98,29 @@ To run all tests, run the following command:
119
98
npx playwright test --grep-invert "@setup"
120
99
```
121
100
122
-
123
-
This command will run all tests located in the `base-tests` directory. If you have custom tests in the `test` folder, these will be used instead of their `base-tests` counterpart.
124
-
101
+
This command will run all tests located in the `base-tests` directory. If you have custom tests in the `tests` folder, these will be used instead of their `base-tests` counterpart.
125
102
126
103
You can also run a specific test file:
127
104
128
105
```bash
129
-
npx playwright testtests/example.test.ts
106
+
npx playwright test example.spec.ts
130
107
```
131
108
132
-
133
109
The above commands will run your tests, then offer a report. You can also use [the UI mode](https://playwright.dev/docs/running-tests#debug-tests-in-ui-mode) to see what the tests are doing, which is helpful for debugging. To open up UI mode, run this command:
134
110
135
-
136
111
```bash
137
112
npx playwright test --ui
138
113
```
139
114
140
-
141
115
Playwright also offers a trace view. While using the UI mode is seen as the default for developing and debugging tests, you may want to run the tests and collect a trace instead. This can be done with the following command:
142
116
143
-
144
117
```bash
145
118
npx playwright test --trace on
146
119
```
147
120
148
-
149
121
### Skipping specific tests
150
122
151
-
Certain `spec` files and specific tests are used as a setup. For example, all setup tests (such as creating an account and setting a coupon code in your Magento 2 environment) have the tag ‘@setup’. Since these only have to be used once (or in the case of our demo website every 24 hours), most of the time you can skip these. These means most of the time, using the following command is best. This command skips both the `user can register an account` test, as well as the whole of `base/setup.spec.ts`.
152
-
123
+
Certain `spec` files and specific tests are used as a setup. For example, all setup tests (such as creating an account and setting a coupon code in your Magento 2 environment) have the tag ‘@setup’. Since these only have to be used once (or in the case of our demo website every 24 hours), most of the time you can skip these. These means most of the time, using the following command is best. These tests, including `user_can_register_an_account` and all tests in `base-tests/setup.spec.ts` (or any custom setup in `tests/setup.spec.ts`), can be skipped most of the time.
153
124
154
125
```bash
155
126
npx playwright test –-grep-invert @setup
@@ -159,45 +130,72 @@ npx playwright test –-grep-invert @setup
159
130
160
131
Most tests have been provided with a tag. This allows the user to run specific groups of tests, or skip specific tests. For example, tests that check the functionality of coupon codes are provided with the tag ‘@coupon-code’. To run only these tests, use:
161
132
162
-
163
133
```bash
134
+
164
135
npx playwright test –-grep @coupon-code
165
136
```
166
137
167
-
168
138
You can also run multiple tags with logic operators:
169
139
170
-
171
140
```bash
141
+
172
142
npx playwright test –-grep ”@coupon-code|@cart”
173
143
```
174
144
175
-
176
145
Use `--grep-invert` to run all tests **except** the tests with the specified test. Playwright docs offer more information: [Playwright: Tag Annotations](https://playwright.dev/docs/test-annotations#tag-tests). The following command, for example, skips all tests with the tag ‘@coupon-code’.
177
146
178
-
179
147
```bash
148
+
180
149
npx playwright test –-grep-invert @coupon-code
181
150
```
182
151
152
+
### Customizing the testing suite
183
153
154
+
The newly created `tests` folder will become your base of operations. In here, you should use the same folder structure that you see in `base-tests`. For example, if your login page works slightly differently from the demo website version, create a copy of `login.page.ts` and place it `tests/config/poms/frontend/` and make your edits in this file. The next time you run the testing suite, it will automatically use these custom files.
184
155
185
-
---
156
+
#### Module Imports
157
+
158
+
To keep the project structure clean and maintainable, we use **TypeScript path aliases** via `tsconfig.json`. This allows you to use the `@` prefix in imports instead of relative paths like `../../../`.
186
159
187
-
##✏️ Customizing the testing suite
160
+
#### Guidelines
188
161
189
-
The newly created `tests` folder will become your base of operations. In here, you should use the same folder structure that you see in `base-tests`. For example, if your login page works slightly differently from the demo website version, create a copy of `login.page.ts` and place it `tests/config/poms/frontend/` and make your edits in this file. **You will also have to copy the corresponding**`.spec.ts`**file**. The next time you run the testing suite, it will automatically use these custom files.
162
+
**Always use `@` imports** when importing from one of the core module folders, such as:
190
163
164
+
-`@poms` – Page Object Models
165
+
-`@config` – Test configuration and data
166
+
-`@utils` – Shared utility functions
167
+
-`@steps` – Common step definitions
168
+
-`@features` – (Optional) Gherkin feature files
169
+
170
+
**Correct Usage**
171
+
172
+
```ts
173
+
import { UIReference } from'@config';
174
+
import { requireEnv } from'@utils/env.utils';
175
+
176
+
importHomePagefrom'@poms/frontend/home.page';
177
+
```
178
+
179
+
**Wrong Usage**
180
+
181
+
```ts
182
+
// ❌ Don't use relative paths
183
+
import { UIReference } from'../config';
184
+
import { requireEnv } from'../utils/env.utils';
185
+
186
+
importHomePagefrom'../poms/frontend/home.page';
187
+
```
188
+
189
+
---
191
190
192
191
### Examples
193
192
194
193
Below are some example tests to illustrate how to write and structure your tests.
195
194
196
-
197
195
**User registration test:**
198
196
199
-
200
197
```javascript
198
+
201
199
/**
202
200
* @feature User Registration
203
201
* @scenario User successfully registers on the website
@@ -206,15 +204,13 @@ Below are some example tests to illustrate how to write and structure your tests
206
204
* @and I submit the form
207
205
* @then I should see a confirmation message
208
206
*/
209
-
test('User can register an account', async ({ page }) => {
0 commit comments