6.3Runbooks for Common QA Tasks

A runbook is a step-by-step procedure for a specific task. Unlike a guide (which explains concepts), a runbook is a checklist that someone can follow without prior knowledge.

Runbook Format

Every runbook should follow a consistent structure:

# 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]

Example: Environment Setup 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 24+ (active LTS) 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

Essential Runbooks for QA Teams

Runbook	Purpose	Who Uses It
Environment setup	Get new team members productive quickly	New hires, returning team members
Test data management	Create, refresh, and manage test data	All QA engineers
Deployment verification	Verify a deployment to staging or production	QA engineers, on-call engineers
Test suite maintenance	Fix flaky tests, update selectors, manage test dependencies	Automation engineers
Incident response for QA	QA-specific steps during an incident	QA engineers during incidents
Release testing	Step-by-step process for release verification	QA engineers before releases
Test environment reset	Reset environments to a clean state	All QA engineers
Access provisioning	How to request and grant access to QA tools	QA leads, new hires