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