Skip to content

Commit 54a0393

Browse files
committed
docs: update docs
1 parent ad48e9d commit 54a0393

File tree

7 files changed

+291
-322
lines changed

7 files changed

+291
-322
lines changed

README.md

Lines changed: 13 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
# Инструмент для e2e тестирования
22

3-
## Настройка окружения для разработки e2e
3+
Библиотека e2e-tools позволяет:
4+
5+
- Развернуть и настроить [CodeceptJS](https://codecept.io/) для написания тестов.
6+
- Развернуть и настроить [Nightwatch.js](https://nightwatchjs.org/) для написания тестов.
7+
- Настроить прогон тестов через GitHub Actions.
8+
- Настроить связку с [Allure TestOps](https://qameta.io/): выгрузка отчетности, запуск автотестов (только для CodeceptJS).
9+
10+
## Настройка окружения для запуска тестов
411

512
1. Установить [Git LFS](https://git-lfs.github.com)
613
1. Установить [Node.js LTS](https://nodejs.org/en/)
@@ -13,96 +20,19 @@
1320

1421
Дополнительные [рекомендации по настройке окружения](./docs/ENVIRONMENT_SETUP.md).
1522

16-
## Написание тест-кейсов
17-
18-
### Синтаксис
19-
20-
- Файлы тестов должны располагаться в папке `e2e-tests\nightwatch\tests` (группировка по папкам допускается)
21-
- Файлы тестов должны иметь название формата `<Наименование файла>.test.js`
22-
- Формат тест-кейса:
23-
24-
```javascript
25-
testcase('Наименование кейса', () => {
26-
<тело кейса>
27-
})
28-
```
29-
30-
- Формат шагов:
31-
32-
```javascript
33-
step('наименование шага', () => {
34-
<команды, которые необходимо выполнить>
35-
})
36-
```
37-
38-
- Формат ожидания:
39-
40-
```javascript
41-
expected('наименование ожидаемого результата', () => {
42-
<команды, которые необходимо выполнить>
43-
})
44-
```
45-
46-
**Пример**
47-
48-
```javascript
49-
testcase('Логаут', () => {
50-
step('кликаем на Аватар', () => {
51-
browser.click('[data-testid="AccountMenu:avatar"]')
52-
})
53-
step('кликаем на Выйти', () => {
54-
browser.click('[data-testid="AccountMenu:logout"]')
55-
})
56-
expected('отображается кнопка Войти', () => {
57-
browser.waitForElementPresent('[data-testid="Header:authLink"]')
58-
})
59-
})
60-
```
61-
62-
**Важно:** `step` и `expected` вне `testcase` выполняться не будут.
63-
64-
При создании тест-кейса рекомендуется использовать [атрибуты для поиска элементов (data-testid)](./docs/DATA_TESTID.md).
65-
66-
### Частые и кастомные команды
67-
68-
Все команды указаны в [документации Nightwatch](https://nightwatchjs.org/api/). В таблице ниже перечислены самые частые из них.
69-
70-
| Команда | Что делает | Пример |
71-
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
72-
| **browser.url()** | Открывает страницу по URL | `browser.url(browser.launch_url)` |
73-
| **browser.click()** | Нажимает на элемент | `browser.click('[data-testid="Header:authLink"]')` |
74-
| **browser.waitForElementPresent()** | Проверяет, что элемент находится на странице | `browser.waitForElementPresent('[data-testid="AuthForm:form"]')` |
75-
| **browser.waitForElementNotPresent()** | Проверяет, что элемент отсутствует на странице | `browser.waitForElementNotPresent('[data-testid="AuthForm:form"]')` |
76-
| **browser.setValue()** | Вводит значение в поле | `browser.setValue('[data-testid="AuthForm:email"]', '[email protected]')` |
77-
| **browser.pause()** | Ожидает указанное время в мс | `browser.pause(5000)` |
78-
| **browser.assert.containsText()** | Проверяет текст внутри элемента с необходимым id | `browser.assert.containsText('[data-testid="PasswordEditForm:informer"]','Пароль успешно изменён')` |
79-
| **browser.moveToElement()** | Наводит курсор на элемент | `browser.moveToElement('[data-testid="EditForm"]', 1, 1)` |
80-
| **browser.assert.screenshotElement()** | Сравнивает скриншот объекта с эталонным скриншотом. Как работает: при самом первом запуске делает эталонный скриншот, при последующих сравнивает новый скриншот с эталоном. | `browser.assert.screenshotElement('[data-testid="EditForm"]','форма редактирования')` |
81-
| **browser.execute(dragAndDrop, ['селектор первого элемента','селектор элемента, куда двигаем'])** | Предоставляет функцию darg-and-drop. Как использовать: выполнить в терминале (достаточно один раз) `yarn add --dev html-dnd` и в начале теста объявить `var dragAndDrop = require('html-dnd').codeForSelectors`. После этого можно пользоваться командой |
82-
| **.assert.screenshotElement()** | Скрывает элементы страницы на скриншоте | `.assert.screenshotElement('[data-test-id="Card:root"]','вид карточки талант отказался',{ hideSelectors: ['[data-test-id="CardResponse:date"]'] })` |
83-
84-
### Полезное
85-
86-
- Браузер стартует в начале каждого тест-кейса и закрывается после его выполнения.
87-
- Изменить время ожидания по умолчанию можно в файле `/e2e-test/e2e-tools` в строке `"waitForConditionTimeout": 10000`.
88-
- После тестового прогона результат запуска сохраняется в отчет (адрес отчета доступен в конце лога запуска).
89-
90-
### Ошибки
91-
92-
| Ошибка | Объяснение |
93-
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
94-
| `Error while running .clickElement() protocol action: An unknown error has occurred` | Возникает при попытке кликнуть на элемент, который есть на странице, но вне видимой части |
95-
| `Error while running "screenshotElement" command: Error: Unsupported image type` | Возникает при попытке сделать скриншот элемента, которого нет на странице, или если эталонный скриншот не удалось считать |
23+
> Обратите внимание, что все команды, касающиеся тестов, необходимо выполнять, находясь в папке e2e-tests.
9624
9725
## Документация
9826

9927
Для тимлидов:
10028

101-
- [Добавление тестов в проект](./docs/SETUP.md)
29+
- [Добавление e2e-tools в проект](./docs/SETUP.md)
10230
- [Конфигурирование e2e-tools](./docs/CONFIGURATION.md)
31+
- [Настройка GitHub Actions для тестов](./docs/GA_CONFIGS.md)
10332

10433
Для всех:
10534

35+
- [Как писать тесты на Nightwatch](./docs/NIGHTWATCH_HINTS.md)
10636
- [Как ревьюить e2e тесты](./docs/REVIEW.md)
10737
- [Атрибуты для поиска элементов (data-testid)](./docs/DATA_TESTID.md)
108-
- [Частые проблемы](./docs/TROUBLESHOOTING.md)
38+
- [Проблемы и подсказки](./docs/TROUBLESHOOTING.md)

docs/CONFIGURATION.md

Lines changed: 2 additions & 178 deletions
Original file line numberDiff line numberDiff line change
@@ -68,182 +68,6 @@ Id браузера можно задать в файле `e2e-tools.json`:
6868
},
6969
```
7070

71-
# Добавление периодических запусков автотестов в 5 шагов!
71+
## Настройка для стендов с базовой авторизацией
7272

73-
## ШАГ 1. Необходимо открыть файл e2e-tools.json
74-
75-
## ШАГ 2. Добавить настройки для запусков
76-
77-
Добавить для ежедневного запуска в 9 утра:
78-
79-
```json
80-
"releaseChannel": "canary",
81-
"periodicRuns": [
82-
{
83-
"name": "Run Nightwatch tests everyday at 9:00",
84-
"slackChannel": "C0129A519T8",
85-
"event": {
86-
"schedule": [{ "cron": "0 9 * * *" }]
87-
},
88-
"urls": ["https://master.professionals.csssr.cloud"],
89-
"commands": [
90-
"yarn et nightwatch:run --browser remote_chrome",
91-
"yarn et nightwatch:run --browser remote_firefox",
92-
]
93-
},
94-
],
95-
```
96-
97-
Добавить для запуска при успешном обновлении стенда при помощи кубереты :
98-
99-
```json
100-
"releaseChannel": "canary",
101-
"periodicRuns": [
102-
{
103-
"name": "Run Nightwatch tests when branch master is updated",
104-
"slackChannel": "C0129A519T8",
105-
"customEvent": "successful-deploy",
106-
"urls": ["https://master.professionals.csssr.cloud"],
107-
"commands": ["yarn et nightwatch:run --browser remote_chrome"]
108-
}
109-
],
110-
```
111-
112-
Пример по [ссылке](https://github.com/CSSSR/professionals-platform-e2e/blob/ee3f5c0ee319632caa1fcbabba1373cc6a232d53/e2e-tests/e2e-tools.json#L6-L14).
113-
114-
Добавить для запуска при успешном обновлении стенда при помощи GitHub Actions:
115-
116-
```json
117-
"releaseChannel": "canary",
118-
"periodicRuns": [
119-
{
120-
"name": "Run Nightwatch tests when branch master is updated",
121-
"slackChannel": "C0129A519T8",
122-
"event": {
123-
"workflow_run": {
124-
"workflows": ["Deploy Workflow Name"],
125-
"types": ["completed"],
126-
"branches": ["master"]
127-
}
128-
},
129-
"urls": ["https://master.professionals.csssr.cloud"],
130-
"commands": ["yarn et nightwatch:run --browser remote_chrome"]
131-
}
132-
],
133-
```
134-
135-
Пример по [ссылке](https://github.com/CSSSR/s7/blob/aa47f1f94a3d9d5e2b7ad4441fd75a3fed1692e5/e2e-tests/e2e-tools.json#L3-L15).
136-
137-
### Подробности
138-
139-
Если указать `"slackChannel": "<channel-id>"`, то результат прогона будет отправляться в слак. ID канала можно найти в его настройках ([видеоинструкция](https://s.csssr.ru/U09LGPMEU/20210709142250.mp4)).
140-
141-
#### 1. Запуск по расписанию.
142-
143-
Время запуска определяется строкой в формате CRON: `0 9 * * *`. Кастомизировать её удобно при помощи сайта [crontab.guru](https://crontab.guru/#0_9_*_*_*).
144-
145-
```json
146-
"event": {
147-
"schedule": [{ "cron": "0 9 * * *" }]
148-
}
149-
```
150-
151-
#### 2. Запуск при успешном деплое.
152-
153-
Такой запуск работает только для тестовых стендов и только для деплоев при помощи [куберты](https://kuberta.csssr.cloud)
154-
155-
```json
156-
"customEvent": "successful-deploy",
157-
```
158-
159-
_Можно запускать тесты на всех созданных стендах, если указать параметр {{url}}. В качестве URL будет использоваться URL стенда._
160-
161-
```json
162-
"urls": ["{{url}}"],
163-
```
164-
165-
#### 3. Запуск при успешном деплое.
166-
167-
Только для деплоев при помощи GitHub Actions
168-
169-
```json
170-
"event": {
171-
"workflow_run": {
172-
"workflows": ["Deploy Workflow Name"],
173-
"types": ["completed"],
174-
"branches": ["master"]
175-
}
176-
}
177-
```
178-
179-
По-умолчанию периодические запуски используют тесты, которые расположены в `default` ветке репозитория. Исключением является ручной запуск Github Action, когда можно задать ветку в `Run workflow`.
180-
181-
Для того, чтобы изменить ветку репозитория, тесты из которой будут использоваться, необходимо задать опцию `testsBranch`.
182-
183-
Использование тестов из ветки самого стенда доступно для события `"customEvent": "successful-deploy"`, необходимо указать `{{branch}}`.
184-
185-
```json
186-
"testsBranch": "{{branch}}",
187-
```
188-
189-
#### Пример
190-
191-
```json
192-
"periodicRuns": [
193-
{
194-
"name": "Run Nightwatch tests everyday at 9:00",
195-
"slackChannel": "C0129A519T8",
196-
"event": {
197-
"schedule": [{ "cron": "0 9 * * *" }]
198-
},
199-
"urls": ["https://master.professionals.csssr.cloud"],
200-
"commands": [
201-
"yarn et nightwatch:run --browser remote_chrome",
202-
"yarn et nightwatch:run --browser remote_firefox",
203-
],
204-
"testsBranch": "test"
205-
}
206-
],
207-
```
208-
209-
В таком случае при автоматическом запуске будут использоваться тесты из ветки,указанной в конфигурационном файле. При ручном запуске будут использоваться тесты из ветки, которая была указана в `Run workflow`.
210-
211-
Каждый URL, указанный в `urls` и каждая команда, указанная в `commands`, создаёт отдельный файл, который можно запустить независимо.
212-
213-
Тесты не запускаются параллельно — если на момент запуска тестов другой запуск ещё идёт, то запуск попадёт в очередь и будет выполнен, когда первый запуск закончится
214-
215-
> _Обратите внимание!_
216-
> Если в файле e2e-tools.json тип браузера “selenium” ("type": "selenium",) [пример](https://github.com/CSSSR/csssr.com/blob/46f58b18d54b7bb7e3733b72b482a5b1c9f18f55/e2e-tests/e2e-tools.json#L26), необходимо исправить имена переменных
217-
>
218-
> БЫЛО:
219-
>
220-
> ```json
221-
> "basicAuth": {
222-
> "credentialsId": "chromedriver",
223-
> "username_env": "CHROMEDRIVER_USERNAME",
224-
> "password_env": "CHROMEDRIVER_PASSWORD"
225-
> },
226-
> ```
227-
>
228-
> НЕОБХОДИМО ИСПРАВИТЬ НА:
229-
>
230-
> ```json
231-
> "seleniumBasicAuth": {
232-
> "username_env": "SELENIUM_USERNAME",
233-
> "password_env": "SELENIUM_PASSWORD"
234-
> },
235-
> ```
236-
237-
## ШАГ 3. Запустить любой тест на удаленном сервере
238-
239-
При первом прогоне будет запрос username и password, которые сразу запишутся в .env
240-
241-
## ШАГ 4. Перегенерировать файлы
242-
243-
Перегенерировать файлы командой `yarn et generate-periodic-runs`
244-
245-
## ШАГ 5. Закоммитить изменения
246-
247-
# Как запустить ран в Actions
248-
249-
[Исчерпывающий скрин](https://s.csssr.ru/UUK0K6P5F/2022-01-18-17-51-21-uyI9E.jpg)
73+
В .env необходмо указать ссылку на стенд вместе с кредами `LAUNCH_URL=https://login:[email protected]/`

0 commit comments

Comments
 (0)