playwright-bdd-step-definitions

What this skill does

# Playwright BDD Step Definitions

Expert knowledge of creating step definitions for Playwright BDD, including step functions, parameter types, fixtures, and Page Object Model integration.

## Overview

Step definitions connect Gherkin steps in feature files to executable code. Playwright BDD uses `createBdd()` to generate type-safe step definition functions that integrate with Playwright's fixtures and assertions.

## Basic Step Definitions

### Creating Step Functions

```typescript
// steps/common.steps.ts
import { createBdd } from 'playwright-bdd';

const { Given, When, Then } = createBdd();

Given('I am on the home page', async ({ page }) => {
  await page.goto('/');
});

When('I click the login button', async ({ page }) => {
  await page.getByRole('button', { name: 'Login' }).click();
});

Then('I should see the dashboard', async ({ page }) => {
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});
```

### Step with Playwright Fixtures

All Playwright fixtures are available in step definitions:

```typescript
import { createBdd } from 'playwright-bdd';

const { Given, When, Then } = createBdd();

Given('I am logged in as {string}', async ({ page, context }, username: string) => {
  // Access page and context fixtures
  await page.goto('/login');
  await page.getByLabel('Username').fill(username);
  await page.getByRole('button', { name: 'Login' }).click();
});

When('I take a screenshot', async ({ page }) => {
  await page.screenshot({ path: 'screenshot.png' });
});

Then('the browser has {int} cookies', async ({ context }, count: number) => {
  const cookies = await context.cookies();
  expect(cookies).toHaveLength(count);
});
```

## Parameter Types

### Built-in Parameters

```typescript
// String parameter: {string}
Given('the user name is {string}', async ({}, name: string) => {
  console.log(name); // "John"
});

// Integer parameter: {int}
When('I wait {int} seconds', async ({}, seconds: number) => {
  await page.waitForTimeout(seconds * 1000);
});

// Float parameter: {float}
Then('the price is {float}', async ({}, price: number) => {
  console.log(price); // 19.99
});

// Word parameter: {word}
Given('I am on the {word} page', async ({ page }, pageName: string) => {
  await page.goto(`/${pageName}`);
});
```

### Anonymous Parameters

Use regex capture groups for flexible matching:

```typescript
// Match any text in quotes
Given(/^I enter "(.*)" in the search box$/, async ({ page }, query: string) => {
  await page.getByRole('searchbox').fill(query);
});

// Match numbers
When(/^I add (\d+) items to cart$/, async ({ page }, count: string) => {
  const quantity = parseInt(count, 10);
  for (let i = 0; i < quantity; i++) {
    await page.getByRole('button', { name: 'Add to Cart' }).click();
  }
});
```

### Custom Parameter Types

Define reusable parameter types:

```typescript
// steps/parameters.ts
import { defineParameterType } from 'playwright-bdd';

defineParameterType({
  name: 'color',
  regexp: /red|green|blue/,
  transformer: (s) => s,
});

defineParameterType({
  name: 'boolean',
  regexp: /true|false/,
  transformer: (s) => s === 'true',
});

defineParameterType({
  name: 'date',
  regexp: /\d{4}-\d{2}-\d{2}/,
  transformer: (s) => new Date(s),
});
```

Using custom parameters:

```typescript
// steps/ui.steps.ts
import { createBdd } from 'playwright-bdd';
import './parameters'; // Import parameter definitions

const { Given, When, Then } = createBdd();

When('I select the {color} theme', async ({ page }, color: string) => {
  await page.getByRole('button', { name: color }).click();
});

Then('dark mode is {boolean}', async ({ page }, enabled: boolean) => {
  if (enabled) {
    await expect(page.locator('body')).toHaveClass(/dark/);
  }
});
```

## Custom Fixtures

### Creating Custom Fixtures

```typescript
// steps/fixtures.ts
import { test as base, createBdd } from 'playwright-bdd';

// Define fixture types
type TestFixtures = {
  todoPage: TodoPage;
  apiClient: ApiClient;
};

// Extend base test with fixtures
export const test = base.extend<TestFixtures>({
  todoPage: async ({ page }, use) => {
    const todoPage = new TodoPage(page);
    await use(todoPage);
  },

  apiClient: async ({ request }, use) => {
    const client = new ApiClient(request);
    await use(client);
  },
});

// Create BDD functions with custom test
export const { Given, When, Then } = createBdd(test);
```

### Using Custom Fixtures in Steps

```typescript
// steps/todo.steps.ts
import { Given, When, Then } from './fixtures';

Given('I have an empty todo list', async ({ todoPage }) => {
  await todoPage.goto();
  await todoPage.clearAll();
});

When('I add a todo {string}', async ({ todoPage }, text: string) => {
  await todoPage.addTodo(text);
});

Then('I should see {int} todos', async ({ todoPage }, count: number) => {
  await todoPage.expectTodoCount(count);
});
```

### Fixture with Setup and Teardown

```typescript
// steps/fixtures.ts
import { test as base, createBdd } from 'playwright-bdd';

export const test = base.extend<{
  authenticatedPage: Page;
}>({
  authenticatedPage: async ({ page, context }, use) => {
    // Setup: Login before test
    await page.goto('/login');
    await page.getByLabel('Email').fill('[email protected]');
    await page.getByLabel('Password').fill('password');
    await page.getByRole('button', { name: 'Login' }).click();
    await page.waitForURL('/dashboard');

    // Use the authenticated page
    await use(page);

    // Teardown: Logout after test
    await page.goto('/logout');
  },
});

export const { Given, When, Then } = createBdd(test);
```

## Page Object Model

### Page Object Definition

```typescript
// pages/TodoPage.ts
import { Page, Locator, expect } from '@playwright/test';

export class TodoPage {
  readonly page: Page;
  readonly input: Locator;
  readonly list: Locator;
  readonly items: Locator;

  constructor(page: Page) {
    this.page = page;
    this.input = page.getByPlaceholder('What needs to be done?');
    this.list = page.getByRole('list');
    this.items = page.getByTestId('todo-item');
  }

  async goto() {
    await this.page.goto('/todos');
  }

  async addTodo(text: string) {
    await this.input.fill(text);
    await this.input.press('Enter');
  }

  async removeTodo(text: string) {
    const item = this.items.filter({ hasText: text });
    await item.hover();
    await item.getByRole('button', { name: 'Delete' }).click();
  }

  async toggleTodo(text: string) {
    const item = this.items.filter({ hasText: text });
    await item.getByRole('checkbox').click();
  }

  async expectTodoCount(count: number) {
    await expect(this.items).toHaveCount(count);
  }

  async expectTodoVisible(text: string) {
    await expect(this.items.filter({ hasText: text })).toBeVisible();
  }

  async clearAll() {
    const count = await this.items.count();
    for (let i = count - 1; i >= 0; i--) {
      await this.items.nth(i).hover();
      await this.items.nth(i).getByRole('button', { name: 'Delete' }).click();
    }
  }
}
```

### Integrating Page Objects with Steps

```typescript
// steps/fixtures.ts
import { test as base, createBdd } from 'playwright-bdd';
import { TodoPage } from '../pages/TodoPage';
import { LoginPage } from '../pages/LoginPage';

export const test = base.extend<{
  todoPage: TodoPage;
  loginPage: LoginPage;
}>({
  todoPage: async ({ page }, use) => {
    await use(new TodoPage(page));
  },
  loginPage: async ({ page }, use) => {
    await use(new LoginPage(page));
  },
});

export const { Given, When, Then } = createBdd(test);
```

```typescript
// steps/todo.steps.ts
import { Given, When, Then } from './fixtures';

Given('I am on the todo page', async ({ todoPage }) => {
  await todoPage.goto();
});

When('I add {string} to my todos', async ({ todoPage }, text: string) => {
  await todoPage.addTodo(text);
});

When('I complete the todo {string}', async ({ todoPage }, text: string) => {
  await todoPage.toggleTodo(text);
});

When('I