199 lines
5.2 KiB
Markdown
199 lines
5.2 KiB
Markdown
# Custom Test Language with Playwright
|
|
|
|
A simple test language that uses Playwright to automate browser testing with custom syntax.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install
|
|
npm run install-browsers
|
|
```
|
|
|
|
## Usage
|
|
|
|
Run a test file:
|
|
```bash
|
|
npm test tests/example.test
|
|
```
|
|
|
|
Run with a specific profile:
|
|
```bash
|
|
node src/cli.js tests/example.test Chrome
|
|
```
|
|
|
|
Run in headed mode (show browser):
|
|
```bash
|
|
node src/cli.js tests/example.test Chrome
|
|
|
|
npm run test:headed
|
|
```
|
|
|
|
Run in headless mode (default):
|
|
```bash
|
|
node src/cli.js tests/example.test Chrome --headless
|
|
```
|
|
|
|
## Variable Validation
|
|
|
|
PlayWrong now provides comprehensive validation for environment variables:
|
|
|
|
### Linting (Static Analysis)
|
|
```bash
|
|
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
|
|
```bash
|
|
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 |