Running flows

How to execute your test flows and understand the results.

Quick Actions

• Run single flow: Click the play button on any flow card
• Run all active: Click "Run All Active Flows" button
• From Dashboard: Use the quick actions panel

Overview

Once you've created a flow, you can run it to execute all its steps automatically. Flowguard simulates user actions and reports whether the flow passed or failed.

Ways to run flows

1. Run a single flow

From the Flows page:

1. Find the flow you want to run
2. Click the Play button on the flow card
3. The flow begins executing immediately
4. Status updates in real-time

From the Dashboard:

1. Locate the flow in the recent flows section
2. Click the Play button on the flow card
3. Monitor execution

From the Flow Editor: Currently, flows must be run from the Flows page or Dashboard. A "Run" button in the editor may be added in the future.

2. Run all active flows

From the Dashboard:

1. Click Run All Active Flows
2. All flows marked as "Active" will execute
3. Monitor progress on the Dashboard

From the Flows page:

1. Click Run All Active in the toolbar
2. All active flows execute in sequence
3. Results update as each flow completes

TIP

Only flows with "Active" status are included when you run all flows. Inactive flows are skipped.

Execution process

When you run a flow, here's what happens:

Initialization

• Status → Running
• Start time recorded
• Browser launched

Step Execution

• Steps run in order
• Actions performed
• Progress tracked

Completion

• Status → Passed/Failed
• Duration calculated
• Results saved

1. Initialization

• Flow status changes to "Running"
• Start timestamp is recorded
• Previous results are cleared

2. Step execution

Steps run in order from top to bottom:

• Each step performs its action
• If a step fails, execution may stop (depending on settings)
• Progress is tracked in real-time

3. Completion

• Final status is determined (Passed or Failed)
• Execution duration is calculated
• Results are saved
• Screenshots are captured (if enabled)

Understanding results

Passed flows

A flow passes when:

• All steps execute successfully
• All assertions are true
• No errors occur
• Execution completes within timeout

Passed flows display:

• Green "Passed" badge
• Checkmark icon
• Duration in milliseconds
• Timestamp of completion

Failed flows

A flow fails when:

• A step encounters an error
• An assertion fails
• An element can't be found
• Timeout is exceeded
• Network issues occur

Failed flows display:

• Red "Failed" badge
• X icon
• Error message
• Which step failed
• Timestamp of failure

Running flows

A flow shows as running when:

• Execution is in progress
• Steps are being processed
• Not yet complete

Running flows display:

• Orange "Running" badge
• Loading spinner
• Current progress

Viewing detailed results

To see detailed information about a flow's execution:

Last run information

Click on any flow to view:

• Status - Passed, Failed, or Running
• Timestamp - When it ran
• Duration - How long it took
• Step Results - Individual step outcomes
• Error Details - If it failed

Step-by-step results

Each step shows:

• Step number and type
• Success or failure status
• Duration
• Error message (if failed)
• Screenshot (if enabled)

Error messages

Common Error Reference - Expand for solutions

Error	Cause	Solution
Element not found	Selector doesn't match	Update selector, add Wait step
Timeout exceeded	Step took too long	Increase timeout, check page load
Navigation failed	URL unreachable	Check URL, verify site is up
Assertion failed	Content doesn't match	Update expected value, check timing

Execution settings

Control how flows execute by configuring these settings:

Timeout

Maximum time (in milliseconds) to wait for each step.

Default: 30000ms (30 seconds)

When to adjust:

• Increase for slow-loading pages
• Decrease for fast actions (quicker failure detection)

Example:

Timeout: 60000  (1 minute for slow pages)
Timeout: 10000  (10 seconds for quick tests)

Retries

Number of times to retry a failed step before marking the flow as failed.

Default: 0 (no retries)

When to adjust:

• Increase for flaky tests (intermittent failures)
• Keep at 0 for reliable tests

Example:

Retries: 3  (Try up to 3 times before failing)

WARNING

High retry counts can hide real issues. Use retries cautiously and investigate why steps fail intermittently.

Screenshots

Capture screenshots during execution for debugging.

Default: Enabled

When to adjust:

• Enable for debugging failed flows
• Disable to speed up execution

Example:

Screenshot: Enabled  (Capture images for review)
Screenshot: Disabled (Faster execution)

Monitoring active flows

Real-time updates

When flows run, you'll see:

• Status badge changes (Running -> Passed/Failed)
• Duration counter updates
• Progress indicators

Multiple flows running

When running multiple flows:

• Each flow executes independently
• Results update as they complete
• No guaranteed order (may run in parallel in future versions)

Canceling execution

You can cancel a running flow at any time. The flow will be marked as "cancelled" and execution stops immediately. Any steps that already completed are still recorded in the results.

Best practices

Before running

Pre-Run Checklist

• [ ] All steps configured correctly
• [ ] Selectors are accurate
• [ ] Descriptions added for clarity
• [ ] Step order makes sense
• [ ] Tested manually in preview

Set appropriate status:

• Mark as Active for regular testing
• Mark as Inactive if still developing

After running

Post-Run Actions

If Passed	If Failed
Note execution time	Check which step failed
Schedule for regular runs	Update selectors if needed
	Adjust timeouts
	Fix and re-run immediately

Regular testing

When to Run Your Flows

Trigger	Priority
WordPress core updates	Critical
Plugin updates	Critical
Theme changes	High
Content modifications	Medium
Code deployments	Critical
Scheduled (automated)	Ongoing

What to test:

• User journeys that matter most
• Features you recently changed
• Common workflows

Troubleshooting

Flow won't start

Possible causes:

• Flow is set to Inactive
• No steps in the flow
• Browser/server issue

Solutions:

1. Verify flow is Active
2. Check that steps exist
3. Refresh the page
4. Check browser console

Flow always fails

Possible causes:

• Selectors are outdated
• Page structure changed
• Timeouts too short
• Element loads slowly

Solutions:

1. Open flow in editor
2. Test each step manually
3. Update selectors using picker
4. Add Wait steps
5. Increase timeouts

Flow passes unexpectedly

Possible causes:

• Assertions are too broad
• Wrong elements being checked
• Site behavior changed

Solutions:

1. Review assertion conditions
2. Make assertions more specific
3. Add more verification steps
4. Test manually to confirm

Slow execution

Possible causes:

• Many Wait steps
• Long timeouts
• Slow page loading
• Many screenshots

Solutions:

1. Reduce Wait durations
2. Optimize timeouts
3. Disable screenshots
4. Remove unnecessary steps
5. Improve site performance

Intermittent failures

Possible causes:

• Timing issues
• Dynamic content
• Race conditions
• Network instability

Solutions:

1. Add Wait steps before actions
2. Increase timeouts
3. Add retries (cautiously)
4. Make selectors more specific
5. Check for AJAX completion

Reading execution logs

Step results

Each executed step records:

• Step number - Position in flow
• Step type - Action performed
• Status - Success or failure
• Duration - Time taken
• Details - Additional information

Error logs

Failed steps include:

• Error type - What went wrong
• Error message - Detailed description
• Stack trace - Technical details (for developers)
• Screenshot - Visual of the failure

Performance data

Execution data includes:

• Total duration - Full flow execution time
• Step durations - Individual step times
• Slowest steps - Performance bottlenecks

Use this data to optimize your flows.

Tips for reliable flows

Make flows resilient

Use stable selectors:

• Prefer IDs and data attributes
• Avoid generated class names
• Don't rely on DOM structure alone

Add appropriate waits:

• Wait after navigation
• Wait for AJAX requests
• Wait for animations

Verify conditions:

• Assert elements are visible before clicking
• Check that the page loaded correctly
• Verify expected content

Handle edge cases

Consider different states:

• Already logged in vs. logged out
• Empty cart vs. items in cart
• Different screen sizes

Account for variability:

• Dynamic content
• Changing timestamps
• Random ordering

Keep flows maintained

Regular updates:

• Review flows monthly
• Update after site changes
• Archive obsolete flows

Document changes:

• Note why selectors changed
• Record when steps were modified
• Explain flow purpose

Advanced topics

Execution order

Currently, flows execute one at a time. The order depends on:

• How they were triggered (single vs. all)
• System scheduling
• Available resources

Data passing

INFO

Data passing between steps (using variables) is a planned feature for future versions.

Conditional steps

INFO

Conditional execution (if/else logic) is a planned feature for future versions.

Next steps

• Step Types - All available actions
• Settings - Configure default behaviors
• Developer Reference - API for custom integrations

Need help?

If flows aren't working as expected:

1. Check this guide for troubleshooting tips
2. Review the Step Types documentation
3. Inspect your site with browser DevTools
4. Verify WordPress and Flowguard are up to date
5. Contact support for assistance