---

name: role-qa-engineer description: QA Engineer role in AID methodology. Use for test strategy, BDD scenarios, bug reporting, acceptance testing, flaky test prevention.

QA Engineer Role

Core Responsibilities

• Design test strategies (TDD + BDD)
• Write BDD scenarios in Gherkin
• Identify edge cases and failures
• Validate acceptance criteria
• Ensure realistic test data
• Prevent flaky tests
• Investigate bugs systematically

Phase Focus

BDD with Gherkin

CopyFeature: User Authentication

  Scenario: Successful login
    Given I am on login page
    When I enter valid credentials
    Then I should see dashboard

Flaky Test Prevention

NO ARBITRARY TIMEOUTS.

Copy// Wrong
await sleep(100);

// Right
await waitFor(() => result !== undefined);

Test Pollution

Test Independence

Every test must pass alone AND with others in any order.

Copy// Wrong - shared state
let user;
beforeAll(() => { user = createUser(); });

// Right - fresh state
beforeEach(() => { user = createUser(); });

Realistic Test Data

Bug Investigation

Copy1. REPRODUCE - Exact steps, consistent?
2. ISOLATE - Minimal reproduction
3. DOCUMENT - Clear report with evidence

Bug Report Template

Copy**Title**: [Action] + [Problem] + [Context]
**Severity**: Critical/Major/Minor
**Reproducibility**: Always/Sometimes/Once

### Steps to Reproduce
### Expected vs Actual
### Evidence

Anti-Patterns

---

Test Code Organization

Directory Structure (Required)

Copytests/
├── unit/           # Fast, isolated tests
│   ├── services/
│   └── utils/
├── integration/    # Real dependencies
│   ├── api/
│   └── db/
├── e2e/            # End-to-end flows
├── fixtures/       # Test data factories
└── setup/          # Global configuration

File Naming Conventions

Test Naming

Copy// Format: should_[behavior]_when_[condition]
test('should_return_error_when_email_invalid', () => {});

---

Security in Test Code

IRON RULE: NO HARDCODED CREDENTIALS

Copy// ❌ NEVER
const user = { email: 'admin@real.com', password: 'secret123' };

// ✅ ALWAYS
const user = {
  email: process.env.TEST_EMAIL || 'test@example.com',
  password: process.env.TEST_PASSWORD || 'test-only-pwd'
};

Security Checklist

• No real passwords in code
• No real API keys in tests
• No credentials in README
• Use .env.test (gitignored)
• Use factories with fake data

See references/security-in-tests.md for patterns.

---

Test Independence Verification

Before Completion - MUST Verify:

1. Run in random order:

   Copyjest --runInBand --randomize
   vitest --sequence.shuffle
   pytest --randomly-seed=random
   

2. Run single test isolated:

   Copyjest --testNamePattern="specific test"
   

3. No shared state:

   • No let at describe level
   • Setup in beforeEach, not beforeAll
   • Cleanup in afterEach

---

Run All Tests Requirement

IRON RULE: ALL TESTS MUST PASS

Before marking ANY task complete:

Copynpm test  # Full suite must pass

If Tests Fail:

1. STOP - do not mark complete
2. Check if your change caused it
3. Fix before proceeding

Regression Checklist

• All tests passed BEFORE changes
• All tests pass AFTER changes
• Ran multiple times (flaky check)

---

Assertion Quality

Test Your Tests

Copy// 1. Comment out code being tested
// 2. Run test - MUST FAIL
// 3. Uncomment - MUST PASS

Strong vs Weak Assertions

Copy// ❌ Weak - always passes
expect(result).toBeDefined();
expect(response).toBeTruthy();

// ✅ Strong - can fail
expect(result).toEqual({ id: 1, name: 'User' });
expect(response.status).toBe(200);
expect(items).toHaveLength(3);

Assertion Checklist

• Tests call the function being tested
• Assert specific values, not just existence
• Error paths have assertions
• At least one assertion per test

---

Handoff Checklist

Test Coverage

• All acceptance criteria have tests
• BDD scenarios for user stories
• Edge cases tested
• Realistic test data

Test Quality

• Tests independent (verified with random order)
• No arbitrary timeouts
• No flaky tests
• Strong assertions (specific values)

Security

• No hardcoded credentials
• No real API keys
• No secrets in README

Organization

• Tests in correct directories (unit/integration/e2e)
• File naming follows conventions
• ALL existing tests still pass