QA-вики и runbooks

Updated Jul 2026

Построение базы знаний, которую ваша команда действительно использует

Разница между полезной базой знаний QA и кладбищем устаревших документов не в том, какой инструмент вы используете, а в дисциплине, которую вы привносите в создание, организацию и поддержку. Отличная QA-вики сокращает время онбординга с недель до дней, предотвращает повторение ошибок, сохраняет институциональные знания и делает всю команду более эффективной. Плохая QA-вики хуже, чем отсутствие вики, потому что люди тратят время, следуя устаревшим инструкциям.

Построение базы знаний QA

Что документировать

Не всё нужно документировать. Избыточная документация так же вредна, как и недостаточная, потому что создаёт шум, скрывающий сигнал. Фокусируйтесь на документировании того, что:

Структура базы знаний

Хорошо организованная база знаний отражает то, как люди ищут информацию: по задаче, а не по типу документа.

Рекомендуемая структура верхнего уровня:

QA Knowledge Base/
├── Getting Started/
│   ├── Onboarding checklist
│   ├── Environment setup
│   ├── Tool access and accounts
│   └── Team norms and processes
├── Testing Guides/
│   ├── By feature area/
│   │   ├── Checkout testing guide
│   │   ├── Search testing guide
│   │   └── Payment testing guide
│   ├── By test type/
│   │   ├── Exploratory testing guide
│   │   ├── Regression testing guide
│   │   └── Performance testing guide
│   └── By platform/
│       ├── Web testing guide
│       ├── Mobile testing guide
│       └── API testing guide
├── Runbooks/
│   ├── Environment management
│   ├── Test data management
│   ├── Deployment verification
│   └── Incident response
├── Tools and Infrastructure/
│   ├── Test framework guide
│   ├── CI/CD pipeline guide
│   ├── Test environment guide
│   └── Monitoring and alerting guide
├── Standards and Templates/
│   ├── Bug report template
│   ├── Test plan template
│   ├── Test case conventions
│   └── Severity definitions
└── Decision Log/
    ├── Why we chose Playwright over Cypress
    ├── Why we use risk-based testing for releases
    └── Why we moved to contract testing

Runbooks для типичных QA-задач

Runbook — это пошаговая процедура для конкретной задачи. В отличие от руководства (которое объясняет концепции), runbook — это чек-лист, которому можно следовать без предварительных знаний.

Формат runbook

Каждый runbook должен следовать единообразной структуре:

# Runbook: [Task Name]

## Purpose
One sentence: what this runbook helps you do.

## Prerequisites
What you need before starting (access, tools, knowledge).

## Steps

### Step 1: [Action]
Specific instruction with exact commands or UI steps.

Expected result: what you should see after this step.

### Step 2: [Action]
...

## Troubleshooting
Common issues and how to resolve them.

## Contacts
Who to ask if you get stuck.

## Last Verified
Date this runbook was last tested: [YYYY-MM-DD]
Owner: [Name]

Пример: Runbook настройки среды

# Runbook: Setting Up the QA Test Environment

## Purpose
Set up a local test environment for running E2E tests against
the staging backend.

## Prerequisites
- macOS or Linux (Windows users: use WSL2)
- Node.js 20+ installed
- Access to the GitHub organization (request via IT portal)
- VPN connected (required for staging access)

## Steps

### Step 1: Clone the Repositories

git clone git@github.com:company/webapp.git git clone git@github.com:company/e2e-tests.git

Expected: both repos cloned without permission errors.

### Step 2: Install Dependencies

cd e2e-tests npm ci npx playwright install

Expected: all packages installed, browsers downloaded.

### Step 3: Configure Environment Variables

cp .env.example .env

Edit `.env` and set:
- `BASE_URL=https://staging.example.com`
- `TEST_USER_EMAIL=qa-test@example.com`
- `TEST_USER_PASSWORD=` (get from 1Password vault "QA Shared")

### Step 4: Verify Setup

npx playwright test --project=chromium tests/smoke.spec.ts

Expected: smoke tests pass (typically 12 tests, ~30 seconds).

## Troubleshooting

| Issue | Cause | Fix |
|---|---|---|
| "Connection refused" on staging URL | VPN not connected | Connect to VPN and retry |
| Browser download fails | Corporate firewall | Use `PLAYWRIGHT_DOWNLOAD_HOST` env var (see wiki) |
| Tests timeout | Staging environment is down | Check #staging-status Slack channel |
| Permission denied on clone | SSH key not configured | Follow the SSH setup guide (link) |

## Contacts
- Environment issues: @devops-team in Slack
- Test framework issues: @qa-platform in Slack

## Last Verified
2026-01-15 by Alice Chen

Необходимые runbooks для QA-команд

Руководства по устранению проблем

Руководства по устранению проблем документируют типичные проблемы и их решения. Они экономят часы отладки, фиксируя решения, которые иначе жили бы только в чьей-то голове.

Формат руководства по устранению проблем

# Troubleshooting: [System or Area]

## Symptom: [What the person observes]

### Possible Cause 1: [Most likely cause]
**How to verify:** [Steps to confirm this is the cause]
**Fix:** [Steps to resolve]

### Possible Cause 2: [Second most likely cause]
**How to verify:** [Steps to confirm]
**Fix:** [Steps to resolve]

### If None of the Above Work
Escalate to [team/person] with the following information:
- [What to include in the escalation]

Пример: Устранение проблем с нестабильными тестами

# Troubleshooting: Flaky E2E Tests

## Symptom: A test passes locally but fails in CI

### Possible Cause 1: Timing issue
**How to verify:** Add a `console.log(Date.now())` before the
failing assertion. Check if the element is rendering later in CI.
**Fix:** Add an explicit wait: `await page.waitForSelector('.element')`
Do NOT use `page.waitForTimeout()` as it masks the real issue.

### Possible Cause 2: Screen size difference
**How to verify:** Check the viewport size in CI config vs local.
CI runs at 1280x720; local may be different.
**Fix:** Set viewport explicitly in the test or test config.

### Possible Cause 3: Test data dependency
**How to verify:** Run the test in isolation (`--grep "test name"`).
If it passes alone but fails in the suite, another test is
modifying shared data.
**Fix:** Ensure each test creates its own data and cleans up.

### Possible Cause 4: Parallel execution race condition
**How to verify:** Run with `--workers=1`. If it passes, the
issue is parallelism-related.
**Fix:** Isolate test data per worker or use test-level locks.

Журналы решений

Журналы решений фиксируют, почему были сделаны определённые выборы. Они бесценны, когда новый член команды спрашивает «почему мы делаем это так?» или когда команда пересматривает решение спустя месяцы.

Формат журнала решений

# Decision: [Title]

**Date:** [YYYY-MM-DD]
**Decision-makers:** [Names]
**Status:** Accepted / Superseded by [link]

## Context
What situation prompted this decision?

## Options Considered

### Option A: [Name]
- Pros: ...
- Cons: ...

### Option B: [Name]
- Pros: ...
- Cons: ...

## Decision
Which option was chosen and why.

## Consequences
What trade-offs were accepted. What follow-up actions are needed.

Пример журнала решений

# Decision: Choosing Playwright over Cypress for E2E Testing

**Date:** 2025-09-15
**Decision-makers:** QA Lead, Engineering Manager, Senior SDET
**Status:** Accepted

## Context
Our Cypress test suite has grown to 350 tests and is experiencing
significant pain points: single-browser limitation (we need Safari),
no native multi-tab support, and slow execution (45 min for full suite).

## Options Considered

### Option A: Stay with Cypress
- Pros: No migration cost, team is familiar, large community
- Cons: No Safari support, single-tab only, performance ceiling

### Option B: Migrate to Playwright
- Pros: Multi-browser (including Safari), multi-tab, faster execution,
  better debugging tools, auto-wait reduces flakiness
- Cons: Migration cost (~3 weeks), team retraining needed

### Option C: Use both (Cypress for existing, Playwright for new)
- Pros: No migration risk, gradual transition
- Cons: Two frameworks to maintain, double the learning curve

## Decision
Migrate fully to Playwright (Option B). The migration cost is
justified by the long-term benefits of multi-browser support
and performance improvements.

## Consequences
- 3-week migration sprint dedicated to converting tests
- Team training sessions scheduled for weeks 1-2
- Cypress will be fully removed after migration is verified
- Expected 40% reduction in suite execution time

Поисковость и обнаруживаемость

База знаний, в которой никто не может найти информацию, бесполезна. Инвестируйте в обнаруживаемость.

Тегирование и категоризация

Оптимизация поиска

• Используйте описательные заголовки: «How to Reset the Staging Database», а не «Database Runbook»
• Включайте ключевые слова, которые люди ищут: Если люди ищут «flaky tests», убедитесь, что эта фраза появляется в соответствующем документе
• Пишите вводные абзацы: Большинство поисковых инструментов активно индексируют первый абзац
• Используйте заголовки, совпадающие с вопросами: «How do I set up the test environment?» как заголовок делает страницу находимой для этого точного вопроса

Обслуживание вики: предотвращение гниения документации

Гниение документации — это постепенное накопление устаревшего, неточного и нерелевантного контента, который делает всю базу знаний ненадёжной.

Цикл гниения документации

New docs written → Team relies on docs → Processes change →
Docs become outdated → Team stops trusting docs →
Team stops reading docs → Team stops writing docs →
Knowledge lives only in heads → New docs written (poorly, hastily)

Разрыв цикла

Чек-лист здоровья страницы

Проводите этот чек-лист ежеквартально для каждой активной страницы:

• Информация точна?
• Все команды и URL актуальны?
• Скриншоты актуальны?
• Страница всё ещё нужна? (Проверьте счётчики просмотров)
• У страницы есть владелец?
• Дата «последней проверки» обновлена?
• Все ссылки работают?

Сравнение инструментов

Выбор правильного инструмента

Практическое упражнение

1. Проведите аудит вашей текущей базы знаний QA. Создайте инвентаризацию того, что существует, что устарело и что отсутствует.
2. Напишите один runbook для QA-задачи, которая сейчас живёт только в чьей-то голове (настройка среды, обновление тестовых данных или верификация развёртывания).
3. Создайте руководство по устранению проблем для наиболее типичной проблемы, с которой сталкивается ваша QA-команда.
4. Напишите журнал решений для последнего значимого технического решения вашей команды.
5. Реализуйте ежеквартальный процесс ревью документации: назначьте владельцев, установите даты ревью и создайте механизм отслеживания.

Пример для собеседования: «Я отношусь к документации как к полноценному инженерному результату, а не как к послесловию. В своих командах я внедрял практики docs-as-code, где тестовая документация живёт в репозитории рядом с тестами, проходит через PR-ревью и валидируется CI — включая проверку ссылок и линтинг формата. Я строю базы знаний QA, структурированные по задачам, а не по типам документов, с runbooks для типичных процедур, руководствами по устранению проблем для известных ситуаций и журналами решений, фиксирующими, почему мы приняли определённые решения по тестированию. Я назначаю владельца каждому документу и провожу ежеквартальные ревью актуальности, потому что устаревшая документация хуже, чем отсутствие документации. Когда члены команды уходят, я провожу структурированные сессии извлечения знаний для захвата доменных знаний до того, как они уйдут за дверь. Результат — команда, которая адаптирует новых инженеров за дни вместо недель, избегает повторения прошлых ошибок и сохраняет институциональные знания независимо от кадровых изменений.»