yaml-pptr

yaml-pptr is a library that allows you to control web browsers using Puppeteer by defining your scenarios in YAML. No more verbose Puppeteer scripts - just simple, human-readable configuration files.

Installation

npm install @bloom-perf/yaml-pptr

Quick Start

import { readYamlAndInterpret } from '@bloom-perf/yaml-pptr';

const yaml = `
scenarios:
  - name: Login Test
    location: "https://www.saucedemo.com"
    steps:
      - input:
          selector: "#user-name"
          text: "standard_user"
      - input:
          selector: "#password"
          text: "secret_sauce"
      - click: "#login-button"
      - wait: 2
`;

readYamlAndInterpret(yaml);

Examples

Ready-to-run examples are available in the examples/ directory:

npm run example:login   # Login test with screenshot
npm run example:load    # Load test (3 workers × 2 iterations)

Getting Started

Project Structure

my-automation/
├── scenarios/
│   └── login-test.yaml
├── src/
│   └── runner.ts
├── package.json
└── tsconfig.json

1. Create a YAML scenario

scenarios/login-test.yaml

scenarios:
  - name: Sauce Demo Login
    location: "https://www.saucedemo.com"
    steps:
      - input:
          selector: "#user-name"
          text: "standard_user"
      - input:
          selector: "#password"
          text: "secret_sauce"
      - click: "#login-button"
      - wait: 2
    actions:
      - type: WAIT_FOR_SELECTOR
        selector: ".inventory_list"
        options:
          visible: true
      - type: SCREENSHOT
        path: "screenshots/result.png"
        options:
          fullPage: true

2. Create a runner script

src/runner.ts

import { readYamlAndInterpret } from '@bloom-perf/yaml-pptr';
import * as fs from 'fs';

const yaml = fs.readFileSync('./scenarios/login-test.yaml', 'utf-8');

fs.mkdirSync('./screenshots', { recursive: true });

readYamlAndInterpret(yaml)
  .then(() => console.log('Done!'))
  .catch(console.error);

3. Run it

npx ts-node src/runner.ts

YAML Reference

Scenario Configuration

Property	Type	Default	Description
name	string	Scenario N	Scenario name
browser	chrome | firefox	chrome	Browser to use
run	PARALLEL | SEQUENTIAL	PARALLEL	Worker start strategy
initialDelaySeconds	number	0	Delay before starting
workers	number	1	Number of parallel workers
iterations	number	1	Repetitions per worker
location	string	-	Starting URL
steps	array	-	Simplified syntax
actions	array	-	Full syntax with options

Steps (Simplified Syntax)

click

- click: "#submit-button"

input

- input:
    selector: "#username"
    text: "myuser"

navigate

- navigate: "http://example.com"
- navigate: "$ENV_VAR"

wait

- wait: 3  # seconds

waitForever

- waitForever

Actions (Full Syntax)

Use actions instead of steps when you need advanced options.

GOTO

- type: GOTO
  url: "http://example.com"
  options:
    timeout: 30000
    waitUntil: networkidle0  # load | domcontentloaded | networkidle0 | networkidle2
    referer: "http://referrer.com"

CLICK

- type: CLICK
  selector: "#button"
  options:
    button: left     # left | right | middle
    clickCount: 2    # double-click
    delay: 100       # ms between mousedown/mouseup

TYPE

- type: TYPE
  selector: "#input"
  text: "Hello"
  options:
    delay: 50  # ms between keystrokes

WAIT

- type: WAIT
  milliseconds: 2000

WAIT_FOR_SELECTOR

- type: WAIT_FOR_SELECTOR
  selector: ".loaded"
  options:
    visible: true
    hidden: false
    timeout: 5000

WAIT_FOR_TIMEOUT

- type: WAIT_FOR_TIMEOUT
  timeout: 1000

SCREENSHOT

- type: SCREENSHOT
  path: "screenshot.png"
  options:
    type: png          # png | jpeg
    quality: 80        # jpeg quality (0-100)
    fullPage: true
    omitBackground: false
    encoding: binary   # binary | base64
    clip:
      x: 0
      y: 0
      width: 800
      height: 600

EVALUATE

- type: EVALUATE
  script: "document.title"

SET_VIEWPORT

- type: SET_VIEWPORT
  width: 1920
  height: 1080

PAUSE

- type: PAUSE  # Press Enter to continue

CLOSE

- type: CLOSE

Environment Variables

Use $VAR_NAME syntax in location or navigate:

location: "$BASE_URL"

BASE_URL=https://example.com npx ts-node runner.ts

Indexed Variables

Assign different values to each worker using $VAR[workerIndex]:

scenarios:
  - name: Multi-URL Test
    workers: 3
    location: "$URLS[workerIndex]"
    steps:
      - wait: 2

URLS="https://site1.com,https://site2.com,https://site3.com" npx ts-node runner.ts

Worker 0 gets site1.com, worker 1 gets site2.com, etc.

Load Testing Example

scenarios:
  - name: Load Test
    run: PARALLEL
    workers: 10
    iterations: 5
    location: "https://example.com"
    steps:
      - click: "#action-button"
      - wait: 1

This runs 10 workers in parallel, each executing the scenario 5 times.

Development

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

Apache 2.0