Frontend Testing

TestFlowKit provides powerful browser automation capabilities for testing web applications. This guide covers all frontend testing features.

Browser Support

TestFlowKit currently supports Chromium for browser automation. Support for Firefox and WebKit will be added in future releases.

Navigation

Going to Pages

Use named pages defined in your configuration:

# Using named page
Given the user goes to the "login" page

# Using direct URL
Given the user navigates to "https://example.com/custom-path"

Page Verification

# Verify URL
Then the current URL should be "https://example.com/dashboard"
Then the current URL should contain "/dashboard"

# Verify page title
Then the page title should be "Dashboard"
Then the page title should contain "Dashboard"

Element Interactions

Clicking Elements

# Click a button
When the user clicks the "submit" button

# Click a link
When the user clicks the "about_us" link

# Click any element
When the user clicks the "modal_overlay" element

Form Inputs

# Text input
When the user enters "john@example.com" into the "email" field

# Clear and enter
When the user clears the "search" field
When the user enters "new search" into the "search" field

# Textarea
When the user enters "Long message here" into the "message" field

Select Dropdowns

# Select by visible text
When the user selects "United States" from the "country" dropdown

# Select by value
When the user selects option with value "US" from the "country" dropdown

Checkboxes and Radio Buttons

# Check a checkbox
When the user checks the "terms" checkbox

# Uncheck a checkbox
When the user unchecks the "newsletter" checkbox

# Select radio button
When the user selects the "express_shipping" radio button

Assertions

Visibility

# Element should be visible
Then the "success_message" should be visible
Then the "welcome_banner" should be visible

# Element should not be visible
Then the "error_message" should not be visible
Then the "loading_spinner" should not be visible

Text Content

# Exact content
Then the "heading" should contain "Welcome"

# Partial match
Then the "paragraph" should contain "some text"

# Should not contain
Then the "error_container" should not contain "failed"

Element State

# Enabled/Disabled
Then the "submit_button" should be enabled
Then the "next_button" should be disabled

# Form field value
Then the "email" field should contain "john@example.com"
Then the "email" field should be empty

Element Count

# Count elements
Then there should be 5 "product_card" elements
Then there should be at least 1 "result_item" element

Mouse Actions

Hover

When the user hovers over the "user_menu" element
Then the "dropdown" should be visible

Double Click

When the user double-clicks the "editable_text" element
Then the "edit_input" should be visible

Right Click

When the user right-clicks the "file_item" element
Then the "context_menu" should be visible

Drag and Drop

When the user drags the "item_1" element to the "drop_zone" element

Keyboard Actions

Key Press

# Press Enter
When the user presses the "Enter" key

# Press Escape
When the user presses the "Escape" key

# Keyboard shortcuts
When the user presses "Control+S"
When the user presses "Command+A"

Type Text

# Type into focused element
When the user types "search query"

Scrolling

# Scroll element into view
When the user scrolls to the "footer" element

# Scroll page
When the user scrolls down
When the user scrolls up
When the user scrolls to the bottom of the page
When the user scrolls to the top of the page

Waiting

Explicit Waits

# Wait for time
When the user waits for 2 seconds

# Wait for element
When the user waits for the "results" to be visible
When the user waits for the "loading" to disappear

Implicit Waits

TestFlowKit automatically waits for elements before interacting. Configure timeout:

frontend:
  default_timeout: 1000  # 1 second (in milliseconds)

Screenshots

On Failure

Automatically capture screenshots when tests fail:

frontend:
  screenshot_on_failure: true

Manual Screenshots

When I take a screenshot
When I take a screenshot named "checkout_page"

Iframes

# Switch to iframe
When the user switches to the "payment_iframe" iframe

# Perform actions inside iframe
When the user enters "4111111111111111" into the "card_number" field

# Switch back to main content
When the user switches to the main content

Alerts and Dialogs

# Accept alert
When the user accepts the alert

# Dismiss alert
When the user dismisses the alert

# Enter text in prompt
When the user enters "confirmation text" in the prompt
When the user accepts the alert

Multiple Windows/Tabs

# Switch to new window
When a new window opens
And the user switches to the new window

# Switch back
When the user switches to the original window

# Close current window
When the user closes the current window

Visual Testing

# Capture baseline
When I capture a visual snapshot of "homepage"

# Compare with baseline
Then the "homepage" should match the visual baseline

Best Practices

1. Use Descriptive Element Names

# Good
elements:
  submit_registration_form: "#register-submit"
  
# Bad
elements:
  btn1: "#register-submit"

2. Wait Appropriately

# Good: Wait for specific element
When the user clicks the "load_more" button
And the user waits for the "new_items" to be visible

# Bad: Arbitrary sleep
When the user clicks the "load_more" button
And the user waits for 5 seconds

3. Verify State After Actions

# Always verify the action had the expected effect
When the user clicks the "submit" button
Then the "success_message" should be visible
And the current URL should contain "/confirmation"

Next Steps

• API Testing — REST API testing
• Selectors — Element detection strategies
• Step Definitions — All available steps