Skip to content

Commit

Permalink
docs: update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ilchukovaolga
ilchukovaolga committed Apr 28, 2022
1 parent ad48e9d commit 54a0393
Show file tree
Hide file tree
Showing 7 changed files with 291 additions and 322 deletions.
96 changes: 13 additions & 83 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
# Инструмент для e2e тестирования

## Настройка окружения для разработки e2e
Библиотека e2e-tools позволяет:

- Развернуть и настроить [CodeceptJS](https://codecept.io/) для написания тестов.
- Развернуть и настроить [Nightwatch.js](https://nightwatchjs.org/) для написания тестов.
- Настроить прогон тестов через GitHub Actions.
- Настроить связку с [Allure TestOps](https://qameta.io/): выгрузка отчетности, запуск автотестов (только для CodeceptJS).

## Настройка окружения для запуска тестов

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

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

## Написание тест-кейсов

### Синтаксис

- Файлы тестов должны располагаться в папке `e2e-tests\nightwatch\tests` (группировка по папкам допускается)
- Файлы тестов должны иметь название формата `<Наименование файла>.test.js`
- Формат тест-кейса:

```javascript
testcase('Наименование кейса', () => {
<тело кейса>
})
```

- Формат шагов:

```javascript
step('наименование шага', () => {
<команды, которые необходимо выполнить>
})
```

- Формат ожидания:

```javascript
expected('наименование ожидаемого результата', () => {
<команды, которые необходимо выполнить>
})
```

**Пример**

```javascript
testcase('Логаут', () => {
step('кликаем на Аватар', () => {
browser.click('[data-testid="AccountMenu:avatar"]')
})
step('кликаем на Выйти', () => {
browser.click('[data-testid="AccountMenu:logout"]')
})
expected('отображается кнопка Войти', () => {
browser.waitForElementPresent('[data-testid="Header:authLink"]')
})
})
```

**Важно:** `step` и `expected` вне `testcase` выполняться не будут.

При создании тест-кейса рекомендуется использовать [атрибуты для поиска элементов (data-testid)](./docs/DATA_TESTID.md).

### Частые и кастомные команды

Все команды указаны в [документации Nightwatch](https://nightwatchjs.org/api/). В таблице ниже перечислены самые частые из них.

| Команда | Что делает | Пример |
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **browser.url()** | Открывает страницу по URL | `browser.url(browser.launch_url)` |
| **browser.click()** | Нажимает на элемент | `browser.click('[data-testid="Header:authLink"]')` |
| **browser.waitForElementPresent()** | Проверяет, что элемент находится на странице | `browser.waitForElementPresent('[data-testid="AuthForm:form"]')` |
| **browser.waitForElementNotPresent()** | Проверяет, что элемент отсутствует на странице | `browser.waitForElementNotPresent('[data-testid="AuthForm:form"]')` |
| **browser.setValue()** | Вводит значение в поле | `browser.setValue('[data-testid="AuthForm:email"]', '[email protected]')` |
| **browser.pause()** | Ожидает указанное время в мс | `browser.pause(5000)` |
| **browser.assert.containsText()** | Проверяет текст внутри элемента с необходимым id | `browser.assert.containsText('[data-testid="PasswordEditForm:informer"]','Пароль успешно изменён')` |
| **browser.moveToElement()** | Наводит курсор на элемент | `browser.moveToElement('[data-testid="EditForm"]', 1, 1)` |
| **browser.assert.screenshotElement()** | Сравнивает скриншот объекта с эталонным скриншотом. Как работает: при самом первом запуске делает эталонный скриншот, при последующих сравнивает новый скриншот с эталоном. | `browser.assert.screenshotElement('[data-testid="EditForm"]','форма редактирования')` |
| **browser.execute(dragAndDrop, ['селектор первого элемента','селектор элемента, куда двигаем'])** | Предоставляет функцию darg-and-drop. Как использовать: выполнить в терминале (достаточно один раз) `yarn add --dev html-dnd` и в начале теста объявить `var dragAndDrop = require('html-dnd').codeForSelectors`. После этого можно пользоваться командой |
| **.assert.screenshotElement()** | Скрывает элементы страницы на скриншоте | `.assert.screenshotElement('[data-test-id="Card:root"]','вид карточки талант отказался',{ hideSelectors: ['[data-test-id="CardResponse:date"]'] })` |

### Полезное

- Браузер стартует в начале каждого тест-кейса и закрывается после его выполнения.
- Изменить время ожидания по умолчанию можно в файле `/e2e-test/e2e-tools` в строке `"waitForConditionTimeout": 10000`.
- После тестового прогона результат запуска сохраняется в отчет (адрес отчета доступен в конце лога запуска).

### Ошибки

| Ошибка | Объяснение |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `Error while running .clickElement() protocol action: An unknown error has occurred` | Возникает при попытке кликнуть на элемент, который есть на странице, но вне видимой части |
| `Error while running "screenshotElement" command: Error: Unsupported image type` | Возникает при попытке сделать скриншот элемента, которого нет на странице, или если эталонный скриншот не удалось считать |
> Обратите внимание, что все команды, касающиеся тестов, необходимо выполнять, находясь в папке e2e-tests.
## Документация

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

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

Для всех:

- [Как писать тесты на Nightwatch](./docs/NIGHTWATCH_HINTS.md)
- [Как ревьюить e2e тесты](./docs/REVIEW.md)
- [Атрибуты для поиска элементов (data-testid)](./docs/DATA_TESTID.md)
- [Частые проблемы](./docs/TROUBLESHOOTING.md)
- [Проблемы и подсказки](./docs/TROUBLESHOOTING.md)
180 changes: 2 additions & 178 deletions docs/CONFIGURATION.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,182 +68,6 @@ Id браузера можно задать в файле `e2e-tools.json`:
},
```

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

## ШАГ 1. Необходимо открыть файл e2e-tools.json

## ШАГ 2. Добавить настройки для запусков

Добавить для ежедневного запуска в 9 утра:

```json
"releaseChannel": "canary",
"periodicRuns": [
{
"name": "Run Nightwatch tests everyday at 9:00",
"slackChannel": "C0129A519T8",
"event": {
"schedule": [{ "cron": "0 9 * * *" }]
},
"urls": ["https://master.professionals.csssr.cloud"],
"commands": [
"yarn et nightwatch:run --browser remote_chrome",
"yarn et nightwatch:run --browser remote_firefox",
]
},
],
```

Добавить для запуска при успешном обновлении стенда при помощи кубереты :

```json
"releaseChannel": "canary",
"periodicRuns": [
{
"name": "Run Nightwatch tests when branch master is updated",
"slackChannel": "C0129A519T8",
"customEvent": "successful-deploy",
"urls": ["https://master.professionals.csssr.cloud"],
"commands": ["yarn et nightwatch:run --browser remote_chrome"]
}
],
```

Пример по [ссылке](https://github.com/CSSSR/professionals-platform-e2e/blob/ee3f5c0ee319632caa1fcbabba1373cc6a232d53/e2e-tests/e2e-tools.json#L6-L14).

Добавить для запуска при успешном обновлении стенда при помощи GitHub Actions:

```json
"releaseChannel": "canary",
"periodicRuns": [
{
"name": "Run Nightwatch tests when branch master is updated",
"slackChannel": "C0129A519T8",
"event": {
"workflow_run": {
"workflows": ["Deploy Workflow Name"],
"types": ["completed"],
"branches": ["master"]
}
},
"urls": ["https://master.professionals.csssr.cloud"],
"commands": ["yarn et nightwatch:run --browser remote_chrome"]
}
],
```

Пример по [ссылке](https://github.com/CSSSR/s7/blob/aa47f1f94a3d9d5e2b7ad4441fd75a3fed1692e5/e2e-tests/e2e-tools.json#L3-L15).

### Подробности

Если указать `"slackChannel": "<channel-id>"`, то результат прогона будет отправляться в слак. ID канала можно найти в его настройках ([видеоинструкция](https://s.csssr.ru/U09LGPMEU/20210709142250.mp4)).

#### 1. Запуск по расписанию.

Время запуска определяется строкой в формате CRON: `0 9 * * *`. Кастомизировать её удобно при помощи сайта [crontab.guru](https://crontab.guru/#0_9_*_*_*).

```json
"event": {
"schedule": [{ "cron": "0 9 * * *" }]
}
```

#### 2. Запуск при успешном деплое.

Такой запуск работает только для тестовых стендов и только для деплоев при помощи [куберты](https://kuberta.csssr.cloud)

```json
"customEvent": "successful-deploy",
```

_Можно запускать тесты на всех созданных стендах, если указать параметр {{url}}. В качестве URL будет использоваться URL стенда._

```json
"urls": ["{{url}}"],
```

#### 3. Запуск при успешном деплое.

Только для деплоев при помощи GitHub Actions

```json
"event": {
"workflow_run": {
"workflows": ["Deploy Workflow Name"],
"types": ["completed"],
"branches": ["master"]
}
}
```

По-умолчанию периодические запуски используют тесты, которые расположены в `default` ветке репозитория. Исключением является ручной запуск Github Action, когда можно задать ветку в `Run workflow`.

Для того, чтобы изменить ветку репозитория, тесты из которой будут использоваться, необходимо задать опцию `testsBranch`.

Использование тестов из ветки самого стенда доступно для события `"customEvent": "successful-deploy"`, необходимо указать `{{branch}}`.

```json
"testsBranch": "{{branch}}",
```

#### Пример

```json
"periodicRuns": [
{
"name": "Run Nightwatch tests everyday at 9:00",
"slackChannel": "C0129A519T8",
"event": {
"schedule": [{ "cron": "0 9 * * *" }]
},
"urls": ["https://master.professionals.csssr.cloud"],
"commands": [
"yarn et nightwatch:run --browser remote_chrome",
"yarn et nightwatch:run --browser remote_firefox",
],
"testsBranch": "test"
}
],
```

В таком случае при автоматическом запуске будут использоваться тесты из ветки,указанной в конфигурационном файле. При ручном запуске будут использоваться тесты из ветки, которая была указана в `Run workflow`.

Каждый URL, указанный в `urls` и каждая команда, указанная в `commands`, создаёт отдельный файл, который можно запустить независимо.

Тесты не запускаются параллельно — если на момент запуска тестов другой запуск ещё идёт, то запуск попадёт в очередь и будет выполнен, когда первый запуск закончится

> _Обратите внимание!_
> Если в файле e2e-tools.json тип браузера “selenium” ("type": "selenium",) [пример](https://github.com/CSSSR/csssr.com/blob/46f58b18d54b7bb7e3733b72b482a5b1c9f18f55/e2e-tests/e2e-tools.json#L26), необходимо исправить имена переменных
>
> БЫЛО:
>
> ```json
> "basicAuth": {
> "credentialsId": "chromedriver",
> "username_env": "CHROMEDRIVER_USERNAME",
> "password_env": "CHROMEDRIVER_PASSWORD"
> },
> ```
>
> НЕОБХОДИМО ИСПРАВИТЬ НА:
>
> ```json
> "seleniumBasicAuth": {
> "username_env": "SELENIUM_USERNAME",
> "password_env": "SELENIUM_PASSWORD"
> },
> ```
## ШАГ 3. Запустить любой тест на удаленном сервере
При первом прогоне будет запрос username и password, которые сразу запишутся в .env
## ШАГ 4. Перегенерировать файлы
Перегенерировать файлы командой `yarn et generate-periodic-runs`
## ШАГ 5. Закоммитить изменения
# Как запустить ран в Actions
[Исчерпывающий скрин](https://s.csssr.ru/UUK0K6P5F/2022-01-18-17-51-21-uyI9E.jpg)
В .env необходмо указать ссылку на стенд вместе с кредами `LAUNCH_URL=https://login:[email protected]/`
Loading

0 comments on commit 54a0393

Please sign in to comment.