Custom Test Language with Playwright

A simple test language that uses Playwright to automate browser testing with custom syntax.

Installation

npm install
npm run install-browsers

Usage

Run a test file:

npm test tests/example.test

Run with a specific profile:

node src/cli.js tests/example.test Chrome

Run in headed mode (show browser):

node src/cli.js tests/example.test Chrome 

npm run test:headed

Run in headless mode (default):

node src/cli.js tests/example.test Chrome --headless

Variable Validation

PlayWrong now provides comprehensive validation for environment variables:

Linting (Static Analysis)

node src/cli.js tests/example.test Chrome --lint

• Common variables like $PASSWORD, $PASSWORDMAIL, $EMAIL, $USERNAME show as info messages
• Undefined variables that are not commonly defined show as warnings

Runtime Validation

During execution, undefined variables:

• Show prominent warnings with helpful instructions
• Are used as literal text (e.g., $UNDEFINED_VAR stays as $UNDEFINED_VAR)
• Can be treated as errors with --strict-variables flag

Strict Mode

node src/cli.js tests/example.test Chrome --strict-variables

• Treats undefined variables as errors
• Stops execution immediately when an undefined variable is encountered
• Useful for CI/CD pipelines to ensure all variables are properly set

Test Language Syntax

Profiles

• Chrome - Desktop Chrome (1280x720)
• Mobile - Tablet portrait (768x1024)
• MobileSmall - Phone portrait (390x844)

Commands

use

Define which profiles to run the test on:

use "Chrome" ( "Mobile" , "MobileSmall")
use "Chrome"

open

Navigate to a URL:

open "https://example.com"

dump

Create a dump folder with context, console, DOM, and screenshot:

dump "step 1"

wait

Wait for an element to appear:

wait element=div childText=Login
wait element=div childText="Multi word text"
wait element=input name=firstName
wait element=button id=submit
wait element=button(child=span class="MuiBadge-badge" childText="1")

click

Click on an element:

click element=div childText=Login
click element=button childText="In den Korb"
click element=button id=submit
click element=button(child=span class="MuiBadge-badge" childText="1")

fill

Fill an input field:

fill element=input name=firstName value=John
fill element=input id=email value=john@example.com

break

Pause execution and wait for user key press:

break
break "Check if the form is filled correctly"
break "Verify the page loaded properly"

sleep

Pause execution for a specified number of milliseconds:

sleep 1000
sleep 2500 "waiting for animation"
sleep 500 "let page settle"

jumpIf

Jump over a specified number of commands if an element exists:

jumpIf element=span childText="Server-Warenkorb" jump=4
jumpIf element=div id="error-message" jump=2

jumpIfNot

Jump over a specified number of commands if an element doesn't exist:

jumpIfNot element=span childText="Server-Warenkorb" jump=4
jumpIfNot element=div id="success-message" jump=2

Element Selectors

You can combine multiple attributes:

• element=div - Element type
• childText=Login - Element containing text
• childText="Multi word text" - Element containing text with spaces (use quotes)
• name=firstName - Element with name attribute
• id=submit - Element with id attribute
• class=button - Element with class attribute
• class="MuiBadge-badge" - Element with class containing spaces/special chars (use quotes)
• href=/path/to/page - Element with href attribute (for links)

Child Element Syntax (NEW)

Target elements that contain specific child elements:

• element=button(child=span childText="1") - Button containing span with text "1"
• element=div(child=a href="/home") - Div containing link to "/home"
• element=form(child=input name="email") - Form containing input with name "email"
• element=nav(child=button class="menu-toggle") - Nav containing button with class "menu-toggle"

Legacy Child Syntax (Still Supported)

• child=span class="MuiBadge-badge" - Find child element with specific attributes (legacy)

Output

Test results are saved in the test-results directory, organized by profile name. Each dump creates a subfolder containing:

• context.json - Page context (URL, title, timestamp, viewport)
• console.json - Console messages
• dom.html - Beautified DOM structure
• screenshot.png - Full page screenshot

Example Test File

// Example test
use "Chrome" ( "Mobile" , "MobileSmall")
open "https://example.com"
dump "initial load"
sleep 1000 "let page settle"
wait element=div childText=Example
click element=div childText=Example
sleep 500 "wait for click animation"
dump "after click"
wait element=input name=search
fill element=input name=search value=test
sleep 300 "wait for input to register"
dump "form filled"
break "Final check before ending"

Running Modes

• Headless Mode (default): Browser runs in background, faster execution
• Headed Mode: Browser window is visible, great for debugging and watching tests run
• Break Command: Pauses execution for manual inspection when using headed mode