SKILLs.md для QA: як навчити AI писати автотести на Playwright саме такі, як тобі треба

💡 Усі статті, обговорення, новини про тестування — в одному місці. Приєднуйтесь до QA спільноти!

Мене звати Михайлюк Віталій, я QA Automation Engineer у TechMagic team та додатково допомагаю моїм друзям із Testomat.io реалізовувати цікаві QA челенджі. У своїй роботі щодня використовую Playwright, TypeScript та AI-агентів на кшталт Claude Code і Cursor.

У цій статті я зібрав 7 правил, які ми з командою сформували на основі реальних проблем з автотестами та тестуванням загалом. Також поділюся з вами готовим безкоштовним скілом, який можна адаптувати під ваш проєкт.

NB: ці правила не універсальні. У кожної компанії свої процеси, архітектура, підходи до тестування та пріоритети. Але я впевнений, що хоча б частина правил, які ми з командою сформували в ході нашої тестувальної роботи, може бути корисною і для вашого проєкту.

Робота з AI-тулами як окремий вид мистецтва

Не боріться з кожною помилкою AI-агента окремо. Повторювані помилки перетворюйте на правила, а правила — на skill.

AI справді може значно спростити роботу QA Automation Engineer. Він швидко розбирається в репозиторії, знаходить потрібний компонент, розбирається в API, пише новий тест і навіть самостійно його запускає.

AI може працювати з тестом ще послідовніше. Наприклад, у CodeceptJS через MCP-інтеграцію агент може виконувати тест покроково прямо в браузері: виконати дію, перевірити результат і лише після успішної перевірки додати цей крок у тест. Або в Claude Code за допомогою розширення Chrome або Firefox. Це більше схоже на те, як тест створює людина: спочатку проклікує сценарій, перевіряє результат кожного кроку, а потім фіксує робочий варіант у коді.

Але щоб правильно працювати з AI-тулами, потрібно багато часу. Спочатку під час написання тестів наш АІ-агент використовував однакові тестові дані, додавав waitForTimeout(), створював надто великі E2E-сценарії та перевіряв URL замість реального результату операції. І все це призводило до непрацюючого коду.

Таким чином, багато чого я навчився саме на власних помилках: пробував різні підходи, отримував не той результат, виправляв його.

Потім зрозумів, що набагато корисніше не виправляти одну й ту саму проблему. Варто пояснити AI правило один раз і використати його в skill для AI-агента.

Правила, з яких створений skill

Нижче описані Automation Antipatterns, які допомогли нам зробити роботу з AI простішою, а тести — якіснішими.

Правило 1: Кожен тест має власні дані

Коли десятки тестів запускаються паралельно в CI, вони можуть використовувати одні й ті самі дані. Наприклад, один тест створює Demo Project, інший використовує того самого користувача, третій видаляє проєкт. Потім ми отримуємо нестабільні падіння. Тому в skill ми чітко описали, як саме створювати тестові дані:

### Rules for Test Data Generation
- NEVER hardcode static IDs, emails, or user credentials in test cases.
- ALWAYS use dynamic data generators (e.g., `@faker-js/faker` or test data factories).
- Ensure test data cleanup or isolation via setup/teardown hooks (`beforeEach`, `afterEach`).

Наприклад, замість статичного Demo Project тест створює власну назву:

const user = await userFactory.create();
const projectName = `Project ${faker.string.nanoid(6)}`;

Правило 2: Патерни очікування для фреймворку

Коли AI не знаходить результат одразу, він може просто додати п’ять секунд очікування:

await page.waitForTimeout(5000);

Але система може бути готова через секунду, а може через сім. Це прямий шлях до сповільнення тест-ранів та флакі-тестів через мережеві затримки. Тому в skill ми описали не тільки те, що не потрібно використовувати, а й що робити замість цього:

### Anti-Patterns to Avoid: Flakiness
- DO NOT use explicit sleep delays (`page.waitForTimeout()`, `Thread.sleep()`).
- ALWAYS wait for specific UI state transitions or explicit network responses:
  - Example: `await page.waitForResponse('/api/v1/users')`
  - Example: `await expect(locator).toBeVisible()`)

Хороший тест чекає саме на потрібний результат:

const responsePromise = page.waitForResponse(r => r.url().includes('/api/v1/users') && r.ok());
await page.getByRole('button', { name: 'Save' }).click();
await responsePromise;

Тепер тест продовжує виконання, щойно з’являється потрібний стан, і не падає через те, що операція зайняла трохи більше часу.

Правило 3: The Iceberg Test

AI любить створювати довгі user journeys. Наприклад: зареєструвати користувача, створити проєкт, імпортувати тести, налаштувати середовище, запустити тести, відкрити звіт і експортувати його в PDF.

І начебто це хороший E2E-тест, але його складно дебажити. Якщо він падає на етапі реєстрації, ми вже нічого не знаємо про імпорт, запуск, звіт або експорт. Попросіть модель декомпозувати сценарії та використовувати API-передумови для підготовки стану.

### Test Architecture Requirements
- Keep individual E2E tests focused on a SINGLE critical assertions path (max 5-7 logical steps).
- Avoid long dependency chains in UI. Use API calls or storage state to set up prerequisites (e.g., seed data via API before opening UI).
- Separate Independent Feature Tests into isolated spec files.

Правило 4: Явна та багатошарова валідація

Наступна проблема — слабкі assertions. AI може перевірити тільки URL:

await expect(page).toHaveURL(/\/runs\//);

Тест буде зеленим, але він не говорить, чи справді запуск відбувся і чи має він правильний стан. Тому в skill ми описали вимогу до явного та багатошарового валідування бізнес-логіки.

### Validation & Assertion Rules
- EVERY test must contain explicit, meaningful assertions verifying business outcomes.
- Avoid checking only URL changes or generic container visibility.
- Assert specific UI elements, state values, or expected API responses.
- Example: Instead of checking if modal exists, check specific success message text and action button states.

Наприклад:

await page.getByRole('button', { name: 'Launch' }).click();
await expect(page.getByTestId('run-summary'))
  .toContainText('4 tests');
await expect(page.getByTestId('run-status'))
  .toHaveText('In progress');
await expect(page.getByRole('row'))
  .toHaveCount(5);

Правило 5: Використання mocks

Коли AI почав використовувати mocks для стабілізації E2E-тестів, це стало наступною перешкодою. На перший погляд, все працює: API завжди повертає очікувану відповідь, тест стає стабільним. Але якщо ми перевіряємо взаємодію UI з власним backend, mock прибирає з тесту саме цю частину системи. Тому встановіть межі використання моків.

### Mocking Strategy Guidelines
- DO NOT mock primary system components under test.
- Use mocks ONLY for:
  1. Third-party integrations (Payment Gateways, External Auth providers).
  2. Unstable/expensive external APIs.
  3. Inducing rare edge-case error states (e.g., HTTP 500/503).
- Prefer Contract/API testing or real test environments for core backend services.

Правило 6: Пріоритетність покриття автотестами

Якщо дати AI user stories і сказати «покрий функціональність», він може почати автоматизувати через UI все підряд: кнопки, повідомлення, дрібні зміни в інтерфейсі.

Тому перед написанням коду AI має знати, що саме йому потрібно перевірити і на якому рівні це краще робити. У skill це виглядає так:

### Test Automation Strategy Prioritization
When analyzing user stories or acceptance criteria:
1. Recommend Unit/Integration coverage first for complex calculations or data transformations.
2. Limit UI Automation to:
   - Smoke scenarios & Critical User Journeys (P0/P1).
   - Stable core workflows (e.g., Auth, Checkout, Search).
3. FLAG items that SHOULD NOT be UI-automated (e.g., third-party captcha, visual layout tweaks, unstable canvas/third-party widgets).

Правило 7: Стратегія автономності

AI може розбити сценарії на кілька тестів, але оформити їх так, щоб Test B працював лише після того, як Test A створив об’єкт у базі. У разі паралельного запуску (workers > 1) такі тести гарантовано проваляться. Зафіксуйте вимогу до повної автономності кожного тесту.

### Test Independence Principles
- Each test MUST be fully isolated and runnable in any order or in parallel.
- NEVER rely on state or side-effects left by previous test cases.
- Use unique entities (e.g., isolated workspaces, unique user prefixes) for concurrent executions.

Як використати цей skill

Наша команда починала з ідеї створити skill для власних потреб в автоматизації тестів. Оскільки цей скіл виглядав цікавим, я вирішив поділитися ним і з іншими, тому готовий варіант цього skill знаходиться у безкоштовній open-source бібліотеці QA skills: testomat.ai/qa-skills.

Його можна використовувати в своїй роботі як є або використати як основу для власного skill.

І я б радив саме другий варіант. Не намагайтеся одразу створити ідеальний skill. Візьміть останні тести, які писав ваш AI-агент, знайдіть у них повторювані проблеми і перетворіть їх на конкретні правила.

Після цього AI почне писати тести не лише за документацією Playwright, а й за правилами вашої команди.

А це вже зовсім інший рівень автоматизації.

Зробіть свій skill

Створіть у структурі вашого проєкту або AI-агента окремий шар інструкцій (наприклад, .cursorrules, файл скіла для Claude Code чи промпт для агента):

У SKILL ми пояснюємо, коли skill потрібно використовувати, даємо контекст про проєкт і додаємо критичні правила:

---
name: automate-manual-test-cases
description: This skill converts manual test cases into production-ready automated test scripts. 
It analyzes the existing automation framework, interprets manual test steps, 
and generates maintainable tests following automation best practices. 
Use this skill whenever the user wants to automate manual test cases,
expand test coverage, or create end-to-end automated flows from existing test documentation.
license: MIT
metadata:
version: 1.0.0
---

Skill Style & Best Practices

## CRITICAL: Anti-Patterns to Avoid (Strict Rules)
1. NO explicit sleeps or hardcoded timeouts.
2. NO hardcoded test data or static credentials.
3. NO chained test dependencies.
4. NO weak assertions (always validate final state explicitly).
## Code Generation Checklist
Before outputting code, verify that:
- [ ] No hardcoded delays were inserted.
- [ ] Test data is isolated/generated dynamically.
- [ ] Assertions verify actual business requirements.

Використання skill — це сучасне практичне рішення: AI-агент знає, що робити саме у вашому проєкті. Ви кастомізуєте його під себе й додаєте або прибираєте правила.

І ще одна ідея

Якщо один skill допомагає AI писати кращі тести, логічним наступним кроком буде створити другий skill, який перевірятиме результат першого.

Наприклад, після генерації тесту окремий skill може пройтися по коду і перевірити: чи немає hardcoded data, чи тест незалежний, чи немає зайвих пауз, чи assertion перевіряє бізнес-результат, чи правильно обрано рівень тестування.

Тоді виходить простий цикл: один AI-інструмент створює тест, інший перевіряє його за правилами вашої команди.

Мені здається, саме в цьому і є один із найпрактичніших способів використовувати AI в automation: навчити AI працювати так, як потрібно саме вашій команді.

А що ви думаєте про skills? Чи використовує ваша компанія skills для AI-агентів? Чи допомагають вони вирішувати реальні проблеми у вашій роботі?

Діліться власним досвідом у коментарях.