ilandahan/AID / skills/role-qa-engineer
role-qa-engineer
VerifiedQA Engineer role in AID methodology. Use for test strategy, BDD scenarios, bug reporting, acceptance testing, flaky test prevention.
| File | Kind | Size |
|---|---|---|
| SKILL.extended.md | markdown | 14.9 KB |
| SKILL.md | skill md | 5.9 KB |
| references/bdd-gherkin-guide.md | markdown | 13.9 KB |
| references/bug-investigation-checklist.md | markdown | 5.3 KB |
| references/code-organization-standards.md | markdown | 8.2 KB |
| references/condition-based-waiting.ts | script | 7.9 KB |
| references/security-in-tests.md | markdown | 6.2 KB |
| references/test-data-examples.md | markdown | 8.7 KB |
| references/test-verification-checklist.md | markdown | 7.2 KB |
| scripts/find-polluter.shexecutable | script | 3.9 KB |
references/bdd-gherkin-guide.md
View on GitHub# BDD Gherkin Guide
Comprehensive guide for writing Behavior-Driven Development tests using Gherkin syntax.
---
## Gherkin Keywords
| Keyword | Purpose | Example |
|---------|---------|---------|
| `Feature` | Describes the feature being tested | `Feature: User Registration` |
| `Scenario` | A single test case | `Scenario: Successful registration` |
| `Given` | Precondition/setup | `Given I am on the registration page` |
| `When` | Action being taken | `When I submit the form` |
| `Then` | Expected outcome | `Then I should see a welcome message` |
| `And` | Additional step (same type as previous) | `And I should receive a confirmation email` |
| `But` | Negative additional step | `But I should not see the registration form` |
| `Background` | Steps run before each scenario | Common setup |
| `Scenario Outline` | Data-driven scenario | Multiple examples |
| `Examples` | Data table for Scenario Outline | Test data |
---
## Basic Structure
```gherkin
Feature: Short feature description
As a [role]
I want [capability]
So that [benefit]
Background:
Given some common precondition
And another common setup step
Scenario: Descriptive scenario name
Given some precondition
When I take some action
Then I should see some outcome
And another expected result
Scenario: Another scenario
Given different precondition
When I take different action
Then I should see different outcome
```
---
## Feature Examples
### Authentication Feature
```gherkin
Feature: User Authentication
As a registered user
I want to log in to my account
So that I can access my personal dashboard
Background:
Given I am on the login page
And the system is available
@smoke @critical
Scenario: Successful login with valid credentials
Given I have a registered account with email "user@example.com"
When I enter email "user@example.com"
And I enter password "SecurePass123!"
And I click the "Log In" button
Then I should be redirected to the dashboard
And I should see "Welcome back" message
And my last login time should be updated
@security
Scenario: Failed login with incorrect password
Given I have a registered account with email "user@example.com"
When I enter email "user@example.com"
And I enter password "WrongPassword"
And I click the "Log In" button
Then I should see error message "Invalid email or password"
And I should remain on the login page
But I should not see any password hints
@security @rate-limiting
Scenario: Account lockout after failed attempts
Given I have a registered account with email "user@example.com"
When I enter incorrect password 5 times
Then I should see error message "Account locked"
And I should receive a password reset email
And I should not be able to attempt login for 15 minutes
```
### E-commerce Feature
```gherkin
Feature: Shopping Cart
As a shopper
I want to manage items in my cart
So that I can purchase products I want
Background:
Given I am logged in as a customer
And the product catalog is available
@happy-path
Scenario: Add single item to empty cart
Given my cart is empty
When I view product "Blue T-Shirt"
And I select size "Medium"
And I click "Add to Cart"
Then my cart should contain 1 item
And the cart total should be "$29.99"
And I should see confirmation "Item added to cart"
@edge-case
Scenario: Add item that exceeds available stock
Given product "Limited Edition Watch" has 2 items in stock
When I try to add 5 of "Limited Edition Watch" to cart
Then I should see error "Only 2 items available"
And my cart should contain 2 items
And I should see "Maximum quantity added"
@business-rule
Scenario: Apply percentage discount code
Given my cart contains items totaling "$100.00"
When I apply discount code "SAVE20"
Then the discount "-$20.00" should be applied
And the cart total should be "$80.00"
And the discount code should be visible in cart summary
```
---
## Scenario Outline (Data-Driven Testing)
### Basic Example
```gherkin
Scenario Outline: Email validation
Given I am on the registration page
When I enter email "<email>"
And I submit the form
Then I should see "<message>"
Examples:
| email | message |
| valid@example.com | Registration successful |
| invalid | Please enter a valid email |
| user@ | Please enter a valid email |
| | Email is required |
| a@b.co | Registration successful |
```
### Complex Example with Multiple Columns
```gherkin
Scenario Outline: Product search with filters
Given I am on the product catalog page
When I search for "<query>"
And I filter by category "<category>"
And I filter by price range "<min_price>" to "<max_price>"
And I sort by "<sort_option>"
Then I should see <result_count> products
And the first product should be "<first_product>"
Examples: Electronics under $500
| query | category | min_price | max_price | sort_option | result_count | first_product |
| laptop | Electronics | 0 | 500 | price_low | 12 | Budget Laptop |
| laptop | Electronics | 0 | 500 | price_high | 12 | Pro Laptop 499 |
| laptop | Electronics | 500 | 1000 | rating | 8 | Top Rated Laptop |
Examples: No results scenarios
| query | category | min_price | max_price | sort_option | result_count | first_product |
| xyznotfound| Any | 0 | 10000 | relevance | 0 | N/A |
```
---
## Tags
### Tag Categories
```gherkin
# Priority/Importance
@critical # Must pass for release
@high-priority # Important but not blocking
@low-priority # Nice to have
# Test Type
@smoke # Quick sanity check
@regression # Full regression suite
@e2e # End-to-end flow
@integration # Integration test
@unit # Unit-level BDD
# Status
@wip # Work in progress
@pending # Not yet implemented
@manual # Requires manual verification
@flaky # Known flaky, needs fixing
# Feature Area
@authentication # Auth-related
@checkout # Checkout flow
@search # Search functionality
# Non-functional
@performance # Performance test
@security # Security test
@accessibility # A11y test
# Environment
@staging-only # Only run in staging
@prod-safe # Safe to run in production
```
### Running Tagged Tests
```bash
# Run only smoke tests
npx cucumber-js --tags "@smoke"
# Run critical but not WIP
npx cucumber-js --tags "@critical and not @wip"
# Run authentication OR checkout tests
npx cucumber-js --tags "@authentication or @checkout"
# Complex expression
npx cucumber-js --tags "(@smoke or @critical) and not @flaky"
```
---
## Step Definition Patterns
### TypeScript/JavaScript (Cucumber.js)
```typescript
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';
// Simple step
Given('I am on the login page', async function() {
await this.page.goto('/login');
});
// Step with string parameter
When('I enter email {string}', async function(email: string) {
await this.page.fill('#email', email);
});
// Step with number parameter
Then('I should see {int} products', async function(count: number) {
const products = await this.page.locator('.product').count();
expect(products).toBe(count);
});
// Step with data table
Given('the following users exist:', async function(dataTable) {
const users = dataTable.hashes();
for (const user of users) {
await this.createUser(user.email, user.password, user.role);
}
});
// Step with doc string
When('I enter the following description:', async function(docString: string) {
await this.page.fill('#description', docString);
});
// Reusable step with regex
When(/^I wait (\d+) seconds?$/, async function(seconds: number) {
await this.page.waitForTimeout(seconds * 1000);
});
```
### Data Tables in Steps
```gherkin
Scenario: Create multiple users
Given the following users exist:
| email | password | role |
| admin@example.com | admin123 | admin |
| user@example.com | user123 | user |
| guest@example.com | guest123 | guest |
When I view the user management page
Then I should see 3 users listed
```
### Doc Strings for Long Text
```gherkin
Scenario: Submit feedback with detailed description
Given I am on the feedback form
When I enter the following feedback:
"""
I really enjoyed using this product!
The interface is intuitive and the features
are exactly what I needed.
One suggestion: add dark mode support.
"""
And I click "Submit"
Then I should see "Thank you for your feedback"
```
---
## Common Patterns
### Page Object Integration
```typescript
// Step using page object
Given('I am logged in as {string}', async function(userType: string) {
const loginPage = new LoginPage(this.page);
const credentials = this.testData.getUser(userType);
await loginPage.login(credentials.email, credentials.password);
});
```
### Shared State Between Steps
```typescript
// World object for shared state
import { setWorldConstructor, World } from '@cucumber/cucumber';
class CustomWorld extends World {
page: Page;
testData: Map<string, any> = new Map();
async saveForLater(key: string, value: any) {
this.testData.set(key, value);
}
getLater(key: string) {
return this.testData.get(key);
}
}
setWorldConstructor(CustomWorld);
// Usage in steps
When('I create an order', async function() {
const orderId = await this.createOrder();
this.saveForLater('orderId', orderId);
});
Then('the order should be confirmed', async function() {
const orderId = this.getLater('orderId');
const status = await this.getOrderStatus(orderId);
expect(status).toBe('confirmed');
});
```
---
## Anti-Patterns and Fixes
### ❌ Too Technical
```gherkin
# BAD: Implementation details
Scenario: API returns correct response
Given I send POST to "/api/users" with body {"name": "John"}
When the server processes the request
Then the response status should be 201
And the response body should contain "id"
```
```gherkin
# GOOD: Business language
Scenario: Create new user account
Given I am on the registration page
When I register with name "John"
Then my account should be created successfully
And I should receive a welcome email
```
### ❌ Too Many Steps
```gherkin
# BAD: Too detailed
Scenario: Complete purchase
Given I am on the home page
And I click the search box
And I type "laptop"
And I press Enter
And I wait for results
And I click the first product
And I click "Add to Cart"
And I click the cart icon
And I click "Checkout"
And I enter shipping address
And I enter payment details
And I click "Place Order"
Then I should see confirmation
```
```gherkin
# GOOD: Abstracted steps
Scenario: Complete purchase
Given I have "laptop" in my cart
When I complete checkout with valid payment
Then I should see order confirmation
```
### ❌ UI Implementation Details
```gherkin
# BAD: Coupled to UI
Scenario: Login
When I click on element "#login-btn"
And I fill input[name="email"] with "user@test.com"
And I fill input[name="password"] with "pass123"
And I click button.submit
```
```gherkin
# GOOD: Behavior focused
Scenario: Login
When I log in with email "user@test.com" and password "pass123"
```
### ❌ Dependent Scenarios
```gherkin
# BAD: Scenarios depend on each other
Scenario: Create user
When I create user "john@test.com"
Then user should exist
Scenario: Login as created user # Depends on previous scenario!
When I login as "john@test.com"
Then I should see dashboard
```
```gherkin
# GOOD: Independent scenarios
Scenario: Login with valid credentials
Given user "john@test.com" exists
When I login as "john@test.com"
Then I should see dashboard
```
---
## Project Structure
```
features/
├── support/
│ ├── world.ts # Custom World class
│ ├── hooks.ts # Before/After hooks
│ └── helpers.ts # Shared utilities
├── step_definitions/
│ ├── common.steps.ts # Shared steps
│ ├── auth.steps.ts # Authentication steps
│ ├── cart.steps.ts # Shopping cart steps
│ └── checkout.steps.ts # Checkout steps
├── authentication/
│ ├── login.feature
│ ├── logout.feature
│ └── password-reset.feature
├── shopping/
│ ├── cart.feature
│ ├── checkout.feature
│ └── payment.feature
└── cucumber.js # Configuration
```
### Cucumber Configuration
```javascript
// cucumber.js
module.exports = {
default: {
requireModule: ['ts-node/register'],
require: ['features/support/**/*.ts', 'features/step_definitions/**/*.ts'],
format: ['progress', 'html:reports/cucumber-report.html'],
formatOptions: { snippetInterface: 'async-await' },
publishQuiet: true,
},
smoke: {
tags: '@smoke',
},
ci: {
tags: 'not @wip and not @manual',
parallel: 4,
},
};
```
---
## Quick Reference
### Good Scenario Checklist
```
□ Title describes the behavior being tested
□ Written in business language
□ 5-8 steps maximum
□ Has Given (context), When (action), Then (outcome)
□ Independent from other scenarios
□ Uses Background for common setup
□ Has appropriate tags
□ Can be understood by non-technical stakeholders
```
### Gherkin Best Practices
| Do | Don't |
|----|-------|
| Use business language | Use technical terms |
| Focus on behavior | Focus on implementation |
| Keep scenarios independent | Create dependent scenarios |
| Use Background for common setup | Repeat setup in each scenario |
| Use Scenario Outline for data variations | Duplicate scenarios |
| Tag for organization | Leave scenarios untagged |
| 5-8 steps per scenario | 15+ steps per scenario |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |