Documentation

TestPerfect provides a comprehensive test automation framework supporting UI testing, API testing, and advanced assertions.

Key features

• Instant element checks using count() for zero-latency DOM presence verification
• Two-pass pattern: instant check first, then wait if not found
• Smart element identification using OpenAI GPT-4o for fallback recovery
• Multiple element locating strategies (role, text, label, XPath, CSS, etc.)
• Async-by-default execution with proper wait mechanisms
• Session management for multiple roles and authentication states
• Comprehensive logging and screenshot capture
• Dialog handling (alert, confirm, prompt, beforeunload)

Execution flow

1. Parse step text
2. Try native handlers (navigate, click, fill, etc.)
3. Try generic selector parser (CSS/XPath extraction)
4. Try AI fallback (GPT-4o for element identification)
5. Log results and capture screenshots

Basic test

Navigate to https://example.com/login
Fill #email with test@example.com
Fill #password with MyPassword123
Click Login
Assert page contains "Dashboard"
Capture text of .order-count as orderCount
Print Your orders: {{orderCount}}

Advanced test

// API Setup
POST https://api.example.com/auth with {"user":"admin"} as auth
Extract {{auth}}.token as token
Set auth token as Bearer {{token}}

// UI Test
Navigate to https://example.com/dashboard
Assert page contains "Welcome"
Save session as admin

// Load User Role
Navigate to https://example.com/login
Fill #email with user@test.com
Fill #password with pass123
Click Login
Save session as user

// Compare Views
Load session admin
Click Settings
Assert page contains "Admin Settings"

Load session user
Click Settings
Assert page contains "User Settings"

Supported actions

• Click buttons, links, and interactive elements
• Fill text inputs and textareas
• Select dropdown options
• Check/uncheck checkboxes and radio buttons
• Type characters with delay
• Press keys and keyboard shortcuts (Ctrl+A, Shift+Tab, etc.)
• Hover/mouseover elements
• Drag and drop
• Scroll (up, down, to element, to top/bottom)
• Focus elements
• Upload files (cross-platform: Mac/Windows)
• Force actions (bypass visibility/enabled checks)
• Auto-fill all form fields with smart dummy data

Auto-fill forms

• Fill all information in register page — auto-fills entire form
• Fill complete form in .signup-section — auto-fills section forms
• Intelligently detects field types (email, password, phone, address, etc.)
• Uses appropriate dummy data: test@example.com for email, TestPass@123! for password
• Handles text inputs, textareas, selects, checkboxes, radio buttons
• Fills only visible, enabled fields

Examples

Click Login Button
Fill #email with test@example.com
Select #country with USA
Check #terms
Press Enter
Type hello
Drag #source to #target
Scroll down 3
Upload ~/Downloads/file.pdf
Force click #hidden-button

// Auto-fill all form fields with dummy data
Fill all information in register page
Fill complete form in #signup-form
Fill all information in settings page

Support for all Playwright locating strategies:

Examples

Click on #login
Click on button:visible
Click on .modal >> button
Click on div:has-text("Login")
Click on //button[contains(text(), 'Submit')]
Fill [data-testid="email"] with test@test.com
Hover over .card:above(.error)

Frame support

• Click inside frame: Click button in iframe .payment-frame
• Fill in frame: Fill #email in frame "stripe-form" with email
• Get from frame: Get text from #total in iframe .summary as totalAmount
• Named frames: Using frame name attribute
• Frame by URL: Get value in frame with URL containing "payments"
• Nested frames: Chaining frame locators

Examples

Click Login in iframe .login-frame
Fill #card-number in frame 'stripe-frame' with 4242424242
Get text from .status in iframe .details as orderStatus
Assert text in iframe .popup contains "Confirm"
Click button in frame with URL containing 'checkout'

Dialog handling

• Accept alert: Accept alert
• Dismiss confirm: Dismiss confirm dialog
• Respond to prompt: Accept prompt with "John"
• Assert dialog content: Assert dialog contains "Are you sure?"
• Capture message: Get dialog message as alertText
• Auto-dismiss by default (no handler needed)
• Handles: alert(), confirm(), prompt(), beforeunload

Examples

Click Delete
Accept alert
Assert page contains "Deleted"

Click Confirm
Assert dialog contains "Are you sure?"
Accept confirm

Get dialog message as message
Print Alert says: {{message}}
Dismiss alert

Basic assertions

• Text content verification: Assert page contains "text"
• Variable comparison: Assert {{var}} equals "expected"
• Numeric comparison: Assert {{count}} > 5
• Contains check: Assert {{email}} contains "@example.com"
• Negating matchers: Assert {{var}} not equals "value"

Advanced assertions

• Soft assertions: Soft assert {{var}} equals "value" (continues on failure)
• Auto-retry: Expect {{var}} equals "expected" with retry 5000ms
• Poll conditions: Expect poll {{status}} until "ready" timeout 10000
• Sorted columns: Assert "Last Name" column is sorted alphabetically
• List operations: Assert all items in #list contain "Active"
• Element states: Assert #button is visible/enabled/editable/stable
• Receives events: Assert button receives events

Element state checks

Assert #button is visible
Assert #input is enabled
Assert #field is editable
Assert .spinner is stable
Assert button receives events
Assert element is not hidden
Assert form is editable

List management

• Count items: Count items in #list
• Get specific: Get item 1 from #list as firstItem
• Assert all: Assert all items in #list contain "Active"
• Assert any: Assert any item in #list contains "Error"
• Get all: Get all items from #list as allItems
• Filter & assert: Assert filtered items in #list with "Pending" count > 0
• Works with table rows, ul/li, div lists, etc.

Examples

Count items in #results
Get item 3 from .list-items as thirdItem
Assert all items in table contain "Verified"
Assert any item in .alerts contains "Critical"
Assert filtered items in #list with "Pending" count == 5
Get all items from .products as products
Print Total products: {{itemCount}}

Supported requests

• GET requests: GET https://api.example.com/users as response
• POST requests: POST https://api.example.com/users with {"name":"John"} as result
• Response assertions: Assert response status equals 200
• Data extraction: Get {{response}}.data.id as userId
• Authentication: Set auth token as Bearer {{token}}
• All subsequent API calls include auth headers

End-to-end API + UI

POST https://api.example.com/login with {"user":"admin","pass":"123"} as auth
Extract {{auth}}.token as token
Set auth token as Bearer {{token}}
Navigate to https://example.com/dashboard
Assert page contains "Welcome"
GET https://api.example.com/profile as profile
Assert {{profile}} contains status 200

Capture operations

• Capture UI text: Capture text of #order-id as orderId
• Extract attributes: Extract alt text of first image as imageAlt
• Get page URL: Get url as appUrl
• Get all list items: Get all items from #list as itemsList
• Get specific item: Get item 1 from #list as firstItem
• Dialog messages: Get dialog message as alertText
• API responses: Stored automatically as JSON
• Use in steps: {{variableName}} syntax available everywhere

Examples

Capture text of .order-id as orderId
Extract alt text of first image as imageName
Get url as startingPage
Get item 1 from .results as firstResult
Print Order: {{orderId}}
Navigate to https://example.com/orders/{{orderId}}
Assert page contains {{imageName}}

Session management

• Save sessions: Save session as admin_role
• Load sessions: Load session admin_role
• Switch roles: Use role regular_user
• API authentication: Set auth token as Bearer {{token}}
• Multiple authenticated users in same test
• Cookie management: Automatic cookie persistence
• Conditional steps: [SKIP IF AUTHENTICATED]
• Logout: Clear session / Clear cookies

Multi-role testing

// Admin setup
Navigate to login
Fill #email with admin@test.com
Fill #password with AdminPass
Click Login
Save session as admin

// User setup
Navigate to login
Fill #email with user@test.com
Fill #password with UserPass
Click Login
Save session as user

// Test both roles
Load session admin
Navigate to /admin
Assert page contains "Admin Panel"

Load session user
Navigate to /dashboard
Assert page contains "User Dashboard"

Run the same test with multiple datasets automatically. Perfect for testing with different user accounts, credentials, or scenarios.

How it works

• Add test data columns in the Test Data tab (email, password, firstName, etc.)
• Add rows of test data (one scenario per row)
• Reference columns in test steps using {{columnName}} syntax
• Each row automatically runs the entire test with substituted values
• All results grouped by data row with individual status

Example workflow

// Test Data Setup (Test Data tab):
// Columns: email, password, firstName
// Row 1: john@test.com, Pass123!, John
// Row 2: jane@test.com, Pass456!, Jane

// Test Steps (referenced in Automated Steps):
Navigate to https://example.com/login
Fill #email with {{email}}
Fill #password with {{password}}
Click Login
Assert page contains "Welcome {{firstName}}"

// Execution:
// Run 1: {{email}}→john@test.com, {{password}}→Pass123!
// Run 2: {{email}}→jane@test.com, {{password}}→Pass456!

Screenshot types

• Full page: Screenshot (entire scrollable page)
• Viewport: Screenshot viewport (visible area only)
• Element: Screenshot #modal (specific element)
• Capture as variable: Screenshot full as pageImage
• Auto-capture: On failure, every 5 steps, on last step

Examples

Screenshot
Screenshot viewport as viewportImg
Screenshot #modal as modalScreenshot
Screenshot full as completePage
Print Screenshot: {{pageImage}}

Output options

• Print: Print message text
• Write: Write test progress
• WriteLine: Write output line
• Log: Log any value
• Console: Console output function
• Variables in output: Print {{variableName}}
• All output captured in step logs

Examples

Print Starting test
Write User logged in
WriteLine Test completed
Print Order ID: {{orderId}}
Log Current status: {{status}}
Print Total: {{total}} | Orders: {{orderCount}}

Column sorting

• Sort columns: Sort by Last Name in Example 1 table
• Verify sort: Verify if Last Name column is sorted alphabetically
• Works with Tablesorter jQuery plugin

Copy to clipboard

Copy test case steps to clipboard for sharing and collaboration

AI recovery

• Automatic fallback to GPT-4o when handlers fail
• Extracts DOM elements and sends to AI
• AI returns JSON with action and selector
• Executes AI-suggested actions
• Logs all AI decisions for debugging

Performance

• Instant element checks with count() (0ms)
• Lazy waits: only wait if element not immediately available
• Async execution prevents timeouts
• Parallel API + UI testing
• Smart retry mechanism with exponential backoff