@esimplicity/stack-tests Documentation

A comprehensive BDD testing framework built on Playwright, providing reusable fixtures, adapters, and step definitions for API, UI, TUI, and hybrid testing.

Quick Navigation

Getting Started

• Installation - Setup and requirements
• Quick Start - Your first test in 5 minutes
• Project Setup - Playwright configuration

Core Concepts

• Architecture - Ports & adapters pattern
• World State - Variables, headers, cleanup
• Test Lifecycle - Fixtures, hooks, teardown
• Tag System - @api, @ui, @tui, @hybrid

Guides

• API Testing - HTTP API testing
• UI Testing - Browser automation
• TUI Testing - Terminal UI testing
• Hybrid Testing - Cross-layer tests
• Custom Adapters - Extend the framework
• Custom Steps - Domain-specific steps
• CI/CD Integration - GitHub Actions, pipelines
• Agent Skills - AI-assisted development
• Upgrading - Version upgrades and migration

Reference

API Reference

• Ports - Interface definitions
• Adapters - Implementation classes
• Fixtures - createBddTest options
• Utilities - Helper functions
• Configuration - Environment variables

Step Reference

• API Steps - @api tagged steps
• UI Steps - @ui tagged steps
• TUI Steps - @tui tagged steps
• Hybrid Steps - @hybrid tagged steps
• Shared Steps - Variables & cleanup

Contributing

• Contributing Guide - How to contribute
• Development Setup - Local environment
• Coding Standards - Style guide
• Testing - Testing the framework
• Adding Ports - Create new ports
• Adding Adapters - Create new adapters
• Adding Steps - Create step definitions
• Release Process - Versioning & publishing

Examples

• Runnable Examples - Working test projects

---

Architecture Overview

Key Features

Feature	Description
Ports & Adapters	Clean separation of interfaces and implementations
Multi-Layer Testing	API, Browser UI, Terminal UI in one framework
BDD Support	Cucumber/Gherkin syntax via playwright-bdd
Auto Cleanup	Resources cleaned up automatically after tests
Variable Interpolation	{varName} syntax in step parameters
Tag Filtering	Run specific test types with @api, @ui, @tui tags

Quick Example

@api
Feature: User Management API

  Scenario: Create and verify user
    Given I am authenticated as an admin via API
    When I POST "/admin/users" with JSON body:
      """
      { "email": "test@example.com", "name": "Test User" }
      """
    Then the response status should be 201
    And I store the value at "id" as "userId"
    
    When I GET "/admin/users/{userId}"
    Then the response status should be 200
    And the value at "email" should equal "test@example.com"

License

See LICENSE in the root of the repository.