ilandahan/AID / skills/cucumber-bdd
cucumber-bdd
VerifiedCucumber BDD integration for AID methodology. Gherkin-first acceptance criteria with executable specifications. Use for writing feature files, step definitions, and running acceptance tests.
| File | Kind | Size |
|---|---|---|
| SKILL.extended.md | markdown | 8.8 KB |
| SKILL.md | skill md | 6.6 KB |
| references/cucumber-go-guide.md | markdown | 9.5 KB |
| references/cucumber-java-guide.md | markdown | 7.2 KB |
| references/cucumber-js-guide.md | markdown | 10.0 KB |
| references/cucumber-python-guide.md | markdown | 7.5 KB |
| references/cucumber-ruby-guide.md | markdown | 5.6 KB |
references/cucumber-js-guide.md
View on GitHub# Cucumber.js Complete Guide
The default and recommended runtime for Cucumber in AID projects.
---
## Prerequisites
- Node.js 18+ (required)
- TypeScript knowledge (recommended)
- npm, yarn, or pnpm
---
## Installation
```bash
# npm
npm install @cucumber/cucumber ts-node --save-dev
# yarn
yarn add @cucumber/cucumber ts-node --dev
# pnpm
pnpm add @cucumber/cucumber ts-node --save-dev
```
---
## Project Structure
```
project/
├── features/
│ ├── auth/
│ │ └── login.feature # Gherkin feature files
│ ├── checkout/
│ │ └── cart.feature
│ ├── step-definitions/
│ │ ├── auth.steps.ts # Step implementations
│ │ ├── checkout.steps.ts
│ │ └── common.steps.ts
│ └── support/
│ ├── world.ts # Custom World class
│ ├── hooks.ts # Before/After hooks
│ └── helpers/ # Utility functions
├── reports/
│ ├── cucumber-report.html # Generated HTML report
│ └── cucumber-report.json # Generated JSON report
├── cucumber.js # Cucumber configuration
├── tsconfig.json # TypeScript config
└── package.json
```
---
## Configuration (cucumber.js)
```javascript
/**
* Cucumber.js Configuration
*
* Profiles:
* - default: Development with progress bar + HTML report
* - ci: CI/CD with JUnit XML, strict mode
* - smoke: Quick validation (@smoke tags)
* - critical: Release gate (@critical tags)
*/
module.exports = {
default: {
require: [
'features/step-definitions/**/*.ts',
'features/support/**/*.ts'
],
requireModule: ['ts-node/register'],
format: [
'progress-bar',
'html:reports/cucumber-report.html',
'json:reports/cucumber-report.json'
],
formatOptions: { snippetInterface: 'async-await' },
publishQuiet: true
},
ci: {
require: [
'features/step-definitions/**/*.ts',
'features/support/**/*.ts'
],
requireModule: ['ts-node/register'],
format: [
'progress',
'html:reports/cucumber-report.html',
'junit:reports/cucumber-junit.xml'
],
publishQuiet: true,
strict: true,
tags: 'not @skip and not @wip'
},
smoke: {
require: ['features/**/*.ts'],
requireModule: ['ts-node/register'],
format: ['progress'],
publishQuiet: true,
tags: '@smoke'
},
critical: {
require: ['features/**/*.ts'],
requireModule: ['ts-node/register'],
format: ['progress-bar', 'html:reports/critical-report.html'],
publishQuiet: true,
strict: true,
tags: '@critical'
}
};
```
---
## TypeScript Configuration
```json
// tsconfig.json
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"outDir": "./dist",
"rootDir": ".",
"resolveJsonModule": true
},
"include": [
"features/**/*.ts",
"src/**/*.ts"
]
}
```
---
## World Setup
The World class provides shared context for all steps in a scenario.
```typescript
// features/support/world.ts
import { setWorldConstructor, World, IWorldOptions } from '@cucumber/cucumber';
import { Page, Browser, chromium } from 'playwright';
import { PrismaClient } from '@prisma/client';
export interface ICustomWorld {
page?: Page;
browser?: Browser;
db: PrismaClient;
testUser?: { id: string; email: string };
response?: Response;
token?: string;
}
export class CustomWorld extends World implements ICustomWorld {
page?: Page;
browser?: Browser;
db: PrismaClient;
testUser?: { id: string; email: string };
response?: Response;
token?: string;
constructor(options: IWorldOptions) {
super(options);
this.db = new PrismaClient();
}
// Helper methods
async login(email: string, password: string): Promise<string> {
const response = await fetch('/api/auth/login', {
method: 'POST',
body: JSON.stringify({ email, password })
});
const { token } = await response.json();
this.token = token;
return token;
}
}
setWorldConstructor(CustomWorld);
```
---
## Hooks (Setup/Teardown)
```typescript
// features/support/hooks.ts
import { Before, After, BeforeAll, AfterAll, BeforeStep, AfterStep } from '@cucumber/cucumber';
import { chromium, Browser } from 'playwright';
let browser: Browser;
// Run once before all scenarios
BeforeAll(async function() {
browser = await chromium.launch({ headless: true });
});
// Run once after all scenarios
AfterAll(async function() {
await browser?.close();
});
// Run before each scenario
Before(async function() {
this.page = await browser.newPage();
});
// Run after each scenario
After(async function(scenario) {
// Screenshot on failure
if (scenario.result?.status === 'FAILED' && this.page) {
const screenshot = await this.page.screenshot({ fullPage: true });
this.attach(screenshot, 'image/png');
}
await this.page?.close();
});
// Tagged hooks
Before('@auth', async function() {
this.token = await this.login('test@example.com', 'password');
});
After('@database', async function() {
await this.db.$executeRaw`ROLLBACK`;
});
```
---
## Integration: Playwright (Browser Testing)
```typescript
// features/step-definitions/browser.steps.ts
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';
Given('I am on the {string} page', async function(path: string) {
await this.page.goto(`http://localhost:3000${path}`);
});
When('I fill in {string} with {string}', async function(field: string, value: string) {
await this.page.fill(`[name="${field}"]`, value);
});
When('I click {string}', async function(text: string) {
await this.page.click(`text=${text}`);
});
Then('I should see {string}', async function(text: string) {
const content = await this.page.textContent('body');
expect(content).toContain(text);
});
Then('the URL should contain {string}', async function(path: string) {
expect(this.page.url()).toContain(path);
});
```
---
## Integration: API Testing (Supertest)
```typescript
// features/step-definitions/api.steps.ts
import { Given, When, Then } from '@cucumber/cucumber';
import request from 'supertest';
import { app } from '../../src/app';
When('I send a GET request to {string}', async function(endpoint: string) {
this.response = await request(app)
.get(endpoint)
.set('Authorization', `Bearer ${this.token || ''}`);
});
When('I send a POST request to {string} with:', async function(endpoint: string, body: string) {
this.response = await request(app)
.post(endpoint)
.send(JSON.parse(body))
.set('Authorization', `Bearer ${this.token || ''}`);
});
Then('the response status should be {int}', function(status: number) {
expect(this.response.status).toBe(status);
});
Then('the response should contain:', function(expected: string) {
const expectedObj = JSON.parse(expected);
expect(this.response.body).toMatchObject(expectedObj);
});
```
---
## Integration: Database (Prisma)
```typescript
// features/step-definitions/database.steps.ts
import { Given, When, Then } from '@cucumber/cucumber';
Given('a user exists with email {string}', async function(email: string) {
this.testUser = await this.db.user.create({
data: {
email,
password: '<hashed-password>',
name: 'Test User'
}
});
});
Then('the user should be saved in the database', async function() {
const user = await this.db.user.findUnique({
where: { email: this.testUser.email }
});
expect(user).not.toBeNull();
});
// Cleanup hook for database scenarios
After('@database', async function() {
await this.db.user.deleteMany({
where: { email: { contains: '@test.com' } }
});
});
```
---
## Running Tests
```bash
# Run all features
npm run cucumber
# Run with specific profile
npx cucumber-js --profile ci
# Run specific feature file
npx cucumber-js features/auth/login.feature
# Run specific scenario by line number
npx cucumber-js features/auth/login.feature:15
# Run with tags
npx cucumber-js --tags "@smoke"
npx cucumber-js --tags "@critical and @auth"
npx cucumber-js --tags "not @wip"
# Dry run (validate syntax only)
npm run cucumber:dry
# Generate HTML report
npm run test:bdd
```
---
## CI/CD: GitHub Actions
```yaml
# .github/workflows/cucumber.yml
name: Cucumber BDD Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:15
env:
POSTGRES_PASSWORD: postgres
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Install Playwright browsers
run: npx playwright install --with-deps chromium
- name: Run Cucumber tests
run: npm run cucumber -- --profile ci
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: cucumber-report
path: reports/
```
---
## Troubleshooting
### Undefined Steps
```bash
# Find undefined steps
npm run cucumber:dry
# Output shows suggested snippets
Given('I am logged in', async function() {
// Write code here
return 'pending';
});
```
### TypeScript Errors
```bash
# Ensure ts-node is registered
npx cucumber-js --require-module ts-node/register
# Check tsconfig.json includes features folder
```
### Slow Tests
```javascript
// cucumber.js - increase timeout
module.exports = {
default: {
worldParameters: {
timeout: 30000 // 30 seconds
}
}
};
```
---
## Resources
- [Cucumber.js Documentation](https://cucumber.io/docs/installation/javascript/)
- [Gherkin Reference](https://cucumber.io/docs/gherkin/reference/)
- [Playwright Documentation](https://playwright.dev/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
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 |