Tester

A web testing automation tool built with Playwright that allows you to test multiple websites and user flows through configuration files.

Features

• 🚀 Automated Web Testing - Test multiple sites and user flows
• 🔐 Authentication Support - Built-in authentication handling
• 🌍 Environment Variables - Dynamic configuration with env variable substitution
• 📊 Progress Tracking - Visual task progress with Listr2
• 🎯 Step-by-Step Testing - Define custom test steps for each site
• 📝 Detailed Logging - Comprehensive test execution logs

Installation

# Install dependencies
bun install

# Or with npm
npm install

Quick Start

1. Create a configuration file (see Configuration section)
2. Set up environment variables
3. Run the tests:

bun start --config config.json

Usage

Command Line Options

bun start --config <config-file> [options]

Options:
  --config <file>    Configuration file path (required)
  --headless         Run browser in headless mode (default: false)
  --retries <number> Number of retry attempts (default: 1)
  --confirm          Pause for manual confirmation between each step (default: false)

Examples

# Basic usage with config file
bun start --config urls.json

# Run with headless browser
bun start --config urls.json --headless

# Run with multiple retries
bun start --config urls.json --retries=3

# Run with manual step confirmation
bun start --config urls.json --confirm

Configuration

Basic Structure

{
  "auth": {
    "url": "{{env.BASE_URL}}/login",
    "endpoint": "{{env.BASE_URL}}/api/oauth/token",
    "data": {
      "grant_type": "password",
      "username": "{{env.USERNAME}}",
      "password": "{{env.PASSWORD}}"
    }
  },
  "sites": [
    {
      "url": "{{env.BASE_URL}}/dashboard",
      "expect": ".dashboard-component",
      "steps": [
        {
          "description": "Open settings",
          "click": ".settings-button"
        },
        {
          "description": "Verify settings page",
          "expect": ".settings-page"
        }
      ]
    }
  ]
}

Configuration Fields

Auth Object (Optional)

{
  url: string;        // URL to navigate to for authentication
  endpoint: string;   // API endpoint for authentication request
  data: Record<string, string>;  // Form data for authentication
}

Site Configuration

{
  url: string;        // URL to test
  expect: string;     // CSS selector to verify page loaded
  steps?: Step[];     // Array of test steps
}

Step Configuration

{
  description?: string;  // Human-readable description
  click?: string;        // CSS selector to click
  expect?: string;       // CSS selector to verify exists
}

Environment Variables

Use {{env.VARIABLE_NAME}} syntax in your configuration to substitute environment variables:

{
  "auth": {
    "url": "{{env.BASE_URL}}/login",
    "data": {
      "username": "{{env.USERNAME}}",
      "password": "{{env.PASSWORD}}"
    }
  },
  "sites": [
    {
      "url": "{{env.BASE_URL}}/dashboard"
    }
  ]
}

Set environment variables before running:

export BASE_URL="https://example.com"
export USERNAME="testuser"
export PASSWORD="testpass"
bun start --config config.json

How It Works

1. Load Configuration - Reads and parses the JSON config file
2. Environment Substitution - Replaces {{env.VARIABLE}} placeholders
3. Browser Setup - Launches Playwright browser instance
4. Authentication - Performs login if auth configuration exists
5. Site Testing - Tests each site sequentially:
   • Navigates to the URL
   • Verifies expected element exists
   • Executes defined steps
6. Cleanup - Closes browser and exits

Error Handling

• Tests continue running even if individual sites fail
• Detailed error messages include site URL and step information
• Authentication failures stop execution immediately
• Network errors are logged with full context

Development

Project Structure

cli/
└── bin.ts                      # CLI entry point and argument parsing
src/
├── tester.ts                   # Main orchestrator and task runner
├── types.ts                    # TypeScript type definitions
├── playwright-check.ts         # Playwright testing logic
├── get-config-file.ts          # Configuration file loader
└── enrich-config-with-env.ts   # Environment variable substitution

Running Tests

# Run the application
bun start

# With specific config
bun start --config urls.json

Dependencies

• @playwright/test - Browser automation
• listr2 - Task runner with progress display
• yargs - Command line argument parsing
• dotenv - Environment variable loading from .env files
• @inquirer/prompts - Interactive CLI prompts (used with --confirm)
• typescript - Type checking and compilation

License

ISC