qa-screenshot-management

QA Screenshot Management Skill

Standardize screenshot capture and organization during QA testing.

Directory Structure

qa-tests/
├── draft/                           # QA test documents by status
├── active/
├── executed/
├── archived/
└── screenshots/
    ├── {test-id}/                   # e.g., QA-20250105-001
    │   ├── 01-initial-state.png     # Numbered sequence
    │   ├── 02-form-filled.png
    │   ├── 03-success-state.png
    │   └── elements/                # Extracted UI elements
    │       ├── login-button.png
    │       ├── email-field.png
    │       └── password-field.png
    ├── baseline/                    # Reference screenshots for comparison
    │   └── {feature}/
    │       └── {state}.png
    └── failures/                    # Failed test evidence
        └── {date}/
            └── {test-id}-{timestamp}.png

Key: Screenshots are stored in qa-tests/screenshots/{test-id}/ where {test-id} matches the QA test document name (e.g., QA-20250105-001).

Naming Convention

Format

{sequence}-{state-description}.{png|jpeg}

Sequence Numbers

• 01- through 99- for ordered steps
• Preserves execution order in file listings

State Descriptions

Use descriptive, kebab-case names:

State	Example Filename
Initial page load	01-initial-state.png
After form fill	02-form-filled.png
Validation error	03-validation-error.png
Success message	04-success-message.png
Modal open	05-modal-open.png
Dropdown expanded	06-dropdown-expanded.png

Bad vs Good Names

Bad	Good
screenshot1.png	01-login-page-loaded.png
test.png	02-credentials-entered.png
error.png	03-invalid-password-error.png
final.png	04-dashboard-after-login.png

When to Capture Screenshots

Always Capture

1. Initial State - Before any test actions
2. After Critical Actions - Form submissions, navigation
3. Error States - Any validation or system errors
4. Success States - Confirmation messages, completed flows
5. Final State - End of test case

Conditional Capture

• Unexpected behavior (document with timestamp)
• Performance issues (loading spinners, delays)
• UI anomalies (layout issues, missing elements)

Screenshot Metadata

Include metadata in test documentation:

### Screenshots

| # | Filename | Description | Step |
|---|----------|-------------|------|
| 1 | 01-initial-state.png | Login page before input | TC-001 Step 1 |
| 2 | 02-credentials-entered.png | Form with test credentials | TC-001 Step 2 |
| 3 | 03-dashboard-loaded.png | Dashboard after successful login | TC-001 Step 3 |

Playwright Screenshot Commands

Basic Capture

// Full viewport
await page.screenshot({ path: 'screenshots/01-initial-state.png' });

// Full page (scrollable)
await page.screenshot({
  path: 'screenshots/02-full-page.png',
  fullPage: true
});

Element Screenshot

// Specific element only
const element = page.locator('.error-message');
await element.screenshot({ path: 'screenshots/03-error-detail.png' });

With Timestamp

const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
await page.screenshot({
  path: `screenshots/failure-${timestamp}.png`
});

Visual Comparison Strategy

Baseline Management

1. Create Baseline

   • Capture reference screenshots on approved build
   • Store in screenshots/baseline/{feature}/
   • Version control baselines

2. Compare During Testing

   • Capture current state
   • Compare against baseline
   • Document differences

Acceptable Differences

Type	Action
Dynamic content (dates, times)	Mask or ignore region
User-specific data	Use consistent test data
Animations	Wait for stable state
Random elements (ads)	Exclude from comparison

Failure Documentation

When a test fails, capture:

screenshots/failures/2025-01-05/
├── QA-20250105-001-TC-002-1704456789.png  # Actual state
├── QA-20250105-001-TC-002-expected.png    # Expected (if applicable)
└── QA-20250105-001-TC-002-diff.png        # Visual diff (if generated)

Failure Screenshot Checklist

• Capture full page showing context
• Capture specific element with issue
• Note browser console errors
• Record timestamp
• Link to test case and step

Cross-Browser Screenshots

Organize by browser when testing multiple browsers:

screenshots/{test-id}/
├── chrome/
│   ├── 01-initial-state.png
│   └── 02-final-state.png
├── firefox/
│   └── ...
└── safari/
    └── ...

Responsive Screenshots

Capture at standard breakpoints:

Device	Width	Suffix
Mobile	375px	-mobile
Tablet	768px	-tablet
Desktop	1280px	-desktop
Wide	1920px	-wide

Example:

01-homepage-mobile.png
01-homepage-tablet.png
01-homepage-desktop.png

Screenshot Cleanup

Retention Policy

Category	Retention
Passing tests	Delete after test run
Failing tests	Keep until issue resolved
Baselines	Keep in version control
Regression evidence	Keep 30 days minimum

Cleanup Command

# Remove screenshots older than 30 days from failures
find qa-tests/screenshots/failures -mtime +30 -delete

Integration with Test Reports

Reference screenshots in test execution logs:

## Test Execution Log

| Date | Tester | Result | Evidence |
|------|--------|--------|----------|
| 2025-01-05 | Jane | FAIL | [Screenshots](./screenshots/QA-20250105-001/) |

Accessibility Screenshot Guidelines

When documenting accessibility issues:

1. Highlight Problem Area

   • Use browser dev tools to highlight element
   • Capture with focus indicator visible

2. Include Context

   • Show surrounding elements
   • Capture screen reader output if relevant

3. Document Fix Verification

   • Before screenshot
   • After screenshot
   • Side-by-side comparison