Flows

Flows are visual workflows that model user journeys through your application. Each flow is a sequence of nodes—login, navigate, action, assertion, wait, condition, setup, notification, and audio input—connected to form a testable path.

Flow Designer also includes a workflow summary card, workflow-level inputs, and validation feedback so you can review a flow at a glance, define reusable run-time parameters, and catch configuration issues before you run or publish.

01When to use flows

• Critical paths: Signup, checkout, billing, onboarding
• High-risk areas: Features that regress often or have complex logic
• Multi-step journeys: Workflows spanning multiple pages or user roles
• Voice and microphone flows: Browser journeys that need spoken prompts, uploaded clips, or repeated audio input during a run

02Node types

Login

Sets the user context for the workflow. Select a credential to act as that user.

In Flow Designer, this step label now appears as Acting As. Use it anywhere the workflow needs to establish or switch user context.

You can also select a credential template directly in the Login node. Use templates when you want the flow to resolve the right credentials at run time instead of binding the step to one saved credential.

Use a credential template when you want to:

• Reuse the same flow across environments or accounts
• Keep login steps flexible for different run contexts
• Standardize authentication setup across similar workflows

Multiple login nodes can appear in segmented flows—for example, before and after a Wait node to re-establish the browser session.

Navigate

Directs the browser to a specific page. Select from discovered pages or enter a custom URL.

Use these URL formats in a Navigate node:

Format	Example	Behavior
Absolute URL	https://app.example.com/settings	Navigates to the exact URL you enter
Root-relative path	/settings	Uses the current environment's base URL, then opens that path
URL with variables or macros	/accounts/{{accountId}}/details	Resolves the variable or macro at runtime before navigating

Use root-relative paths when the same flow needs to run across different environments without editing the node. Use variables or macros when part of the destination changes between runs.

If you enter a root-relative path, Flow Designer keeps the path relative to the active environment. If you include variables or macros in the URL, make sure the referenced values are available at runtime.

The URL field supports the richer macro editor. Type $ to open variable and macro suggestions, then insert values as inline token pills directly in the path.

Action

Performs a user interaction on the current page. Describe what the user should do (for example, "Create a new ticket") and optionally provide input data.

Keep actions focused on a single user goal. See Designing a good test for guidance on action granularity.

Some workflow actions also appear as distinct executable steps during playback and replay instead of being folded into a generic action. Table extraction and Python execution now run as first-class workflow actions, so you can review them as separate steps in run history and timelines.

Use these actions when you need to capture structured data from a page or run custom Python logic as part of the workflow.

Workflow action	Use it for
Table extraction	Capture rows and columns from a table so later steps can reference structured results
Python execution	Run custom Python logic inside the workflow to transform data or drive follow-up steps

Action inputs can now use AI-generated values directly in supported step fields. Use this when you want realistic one-off data such as names, short subjects, or simple form entries without hardcoding a static value into the step.

When you use a generated value, review the rest of the workflow to make sure later steps reference the produced value instead of assuming a fixed string.

Assertion

Verifies expected outcomes. Define a condition to check (for example, "Ticket appears in the list"). In the step configuration, choose how Canary should treat a failed assertion.

Severity	Behavior
Fail	The expected condition is not met and the flow run fails
Warn	The expected condition is not met, but the flow continues and records a warning

Use Fail for checks that must pass before the rest of the workflow can continue. Use Warn for non-blocking checks that still matter and should appear in run results.

Use warning-level assertions when you want to:

• Keep a long workflow running even if a non-critical check does not pass
• Flag unexpected UI states for review without failing the entire run
• Capture soft validation issues that still need human attention

In run views, assertion outcomes appear directly on the relevant steps. You can quickly review which assertions passed, warned, or failed, along with the overall assertion summary for the run.

If a warning-level assertion does not pass, the run continues and the step is marked as a warning. If a fail-level assertion does not pass, the run stops at that step and the run result is marked as failed. Use the step outcome in Run details to confirm whether the assertion passed, warned, or failed when you troubleshoot a run.

Always use agent evaluation: Enable this option to force fresh agent evaluation on every run, bypassing cached results. Use this for assertions that verify dynamic or time-sensitive content, such as:

• Timestamps or dates
• Real-time data feeds
• Content that changes between runs

Assertion fields that support variables and macros also use the richer macro editor, so you can insert dynamic values with $ suggestions and review them as inline token pills while you edit.

Wait

Pauses execution for a specified duration. New Wait steps default to 30 minutes, so if you add a Wait node and do not change the delay, the workflow resumes after 30 minutes.

Use the delay controls in the Configure panel to set the amount of time in minutes, hours, or days. Flow Designer now makes these controls clearer when you add or edit a Wait step, so it is easier to confirm the intended delay before you run or publish.

A Wait step creates a segmented flow—execution pauses, then resumes automatically after the configured delay. Add a Login node after the Wait to re-establish the browser session.

When a run resumes after a Wait, workflow state and step outputs now continue more reliably across the resumed segment. Keep using explicit step boundaries and clear variable references so later steps can consume the right values after the run continues.

Condition

Branches the workflow based on a runtime condition. Define a condition to evaluate, then connect separate paths for the true and false outcomes.

Condition configuration fields that support variables and macros use the richer macro editor. Type $ to insert supported dynamic values without leaving the field.

Setup

References another published flow to run as a prerequisite. Use for shared data creation or environment preparation. See Setup Nodes below.

Notification

Sends an outbound email from your workflow. Use this node when you need to notify a person or team, share run context, or include files as attachments.

Add a Notification node anywhere in the workflow path where the email should send. You can add it from the quick-create menu or by clicking an edge to insert it between two existing nodes. The email sends only when the run reaches that node, so place it after the steps that gather the information you want to include.

Use a Notification node when you want to:

• Send a handoff or status email after a key workflow step
• Alert a team when a branch of the workflow is reached
• Deliver artifacts or files produced during the run as attachments
• Share a human-readable summary with a custom subject and message body

Notification fields such as Subject and Body support the richer macro editor when you include dynamic values. Type $ to insert workflow inputs, variables, and macros as inline token pills.

Audio Input

Plays an uploaded or recorded audio clip into the browser microphone during a run. Use this node when you need to test voice prompts, speech capture, microphone-driven onboarding, or other browser experiences that depend on incoming audio.

Add an Audio Input node where the clip should play in the workflow. Place it after the step that opens or focuses the browser experience that is listening for microphone input.

Use an Audio Input node when you want to:

• Test speech or voice-command flows with a known clip
• Simulate microphone input in browser-based experiences
• Reuse the same recorded phrase across repeated runs
• Keep the workflow moving automatically or wait for playback to finish before the next step

03Building a flow

Create a workflow from scratch, or start from imported source material and continue editing in Flow Designer. Import entry points now include CSV files, test-file conversion, and Jira tickets. Each path creates a draft that opens in the workflow builder so you can review the suggested goal, context, and generated steps before you run or publish.

You can also create a draft from a recording. After the recording finishes, Canary opens the generated workflow and shows live generation progress while the draft is being built. When authoring finishes, Flow Designer refreshes the canvas automatically so you can review the generated steps without manually reloading.

Recordings and replay are now more resilient for harder UI patterns. Expect generated workflows to target icon-only controls, semantic class-based elements, and repeated row-based content more reliably than before.

When you record flows that include repeated lists, tables, or similar row-based layouts, review the generated steps to confirm each action points to the intended row or item. If a step depends on dynamic row content, make that intent explicit in the step description so the authored flow stays easier to replay and debug.

If your workflow changes user context during the journey, add a Login node at the point where the user should switch. Canary now handles in-workflow user switching more dependably during replay, but explicit login boundaries still make the flow easier to understand and maintain.

1. Start from a blank canvas, choose an import option, or create a draft from a recording
2. If you start from a recording, wait for Flow Designer to refresh the canvas after generation finishes, then review the generated draft
3. Click Create Node when the canvas is empty, or click the + button on an existing node
4. To create a connection directly from the add menu, click and hold on a node type, then drag to the target position on the canvas
5. Configure workflow-level details in the Configure panel, including the flow summary, description, and any workflow inputs you want to reuse across runs
6. Select the node type
7. Configure the node in the Configure panel—changes auto-save
8. When you add a step that types into a field, enters keyboard shortcuts, or submits keys, make sure the step clearly opens, selects, or targets the correct input before keyboard entry begins
9. Use AI-generated values in supported step inputs when you need realistic dynamic text such as names, short subjects, or simple form entries without hardcoding them
10. If a later step depends on a generated value, reference that produced value in the next step instead of retyping a fixed string
11. When you add a Wait node, review the default 30 minutes delay and adjust it if your workflow should resume sooner or later
12. When you add or edit a Login node, choose either a saved credential or a credential template based on how you want the flow to resolve authentication at run time
13. Use clear step names and focused step goals so the authored workflow is easier to investigate later in run views
14. Add or refine the workflow description to explain the test purpose and the intended user outcome before you run or publish
15. When you open a specific step, use the breadcrumb at the top of the Configure panel to confirm that you are editing that step and click the workflow breadcrumb to return to the full workflow view

Nodes auto-connect when created from an existing node. Click an edge to insert a node between two existing nodes or delete the connection.

You can also click and hold a node in the add menu, then drag to create the next connected step in one motion. Use this when you want to build a path quickly without placing the node first and reconnecting it afterward.

Use the workflow summary card in the flow view to review key workflow details at a glance while you build.

Flow Designer saves your edits while you build, but it now waits to surface most validation issues until you click Run Flow. Use the canvas and Configure panel to keep editing without immediate validation interruptions, then review any errors or warnings in the run flow experience before you start the run.

If you create a draft from generation, Canary can also start a run automatically after generation succeeds. Review the draft first if you want to confirm the generated steps or workflow inputs before the run begins.

If validation feedback shows that a required input, variable reference, or step configuration is incomplete, resolve it from the run flow experience before you continue. This reduces noise while you edit and keeps validation focused on the point where you are ready to test the draft.

When you configure a workflow or node field that supports variables or macros, use the richer macro editor to build the value inline. Type $ to open suggestions, then select the workflow input, variable, or macro you want to insert.

Use token pills to review dynamic values more easily while you edit. This makes long URLs, messages, and other configuration fields easier to scan before you run or publish.

You can also use AI-generated values more directly in supported step inputs. Generate the value in the step where you need it, then make sure any later step that depends on that text references the produced output.

When you configure an Assertion node, choose the severity that matches the importance of the check. This helps you decide whether a failed assertion should stop the workflow or be recorded as a warning while the workflow continues.

Configure panel

Use the Configure panel to edit the workflow and its individual steps.

• In the workflow view, the panel shows flow-level settings, including the workflow summary, description, and workflow inputs
• Click a node to open that step in the panel
• When a step is open, the breadcrumb at the top of the panel shows your current location
• Click the workflow breadcrumb to go back to the full workflow configuration without closing the editor

Workflow-level fields that support variables and macros use the same richer macro editor as step configuration fields.

Step configuration

Each step opens in the Configure panel for focused editing.

1. Click a node on the canvas
2. Review the breadcrumb at the top of the Configure panel to confirm which step you are editing
3. Update the step settings
4. Click the workflow breadcrumb to return to the full workflow view and continue editing other steps

Changes auto-save as you edit.

For macro-enabled fields, type $ to open suggestions for workflow inputs, variables, and macros. Select a suggestion to insert it as an inline token pill without leaving the field.

For supported step inputs, you can also choose an AI-generated value directly in the field. Use this for realistic dynamic text such as names, short subjects, or simple entries, then reference the produced value in later steps if the workflow needs to reuse it.

For Assertion nodes, set the severity to Fail or Warn based on how the workflow should respond when the condition is not met.

For Login nodes, select either a saved credential or a credential template. In Flow Designer, this step appears as Acting As. Use templates when the same flow needs to authenticate differently based on the run context.

For Wait nodes, confirm the default 30 minutes delay when you first add the step, then update the delay controls if the workflow should pause for a different amount of time.

For steps that type into forms or rely on keyboard input, make sure the step intent clearly identifies the field that should receive focus. Canary now improves focus handling before key entry, but explicit field context still makes authored steps easier to run and debug.

If a step uses keyboard shortcuts or submits keys such as Enter, make sure the prior step leaves focus in the intended field or control. This helps you get the benefit of the improved focus behavior without making the workflow ambiguous.

Notification nodes let you configure the outbound email content directly in the step settings.

Field	Description
Subject	Enter the email subject line
Body	Enter the message content to send in the email body
Attachments	Add one or more files to include with the outbound email

Review the subject and body carefully before you publish the flow. If you attach files, confirm they are the ones you want recipients to receive when the run reaches the node.

Audio Input nodes let you attach or record the clip that should play into the browser microphone.

Field	Description
Audio clip	Upload an audio file or record a clip directly in the browser
Preview	Play the clip in the editor to confirm the audio before you run
Loop playback	Repeat the clip until playback completes or the browser experience captures what it needs
Wait for playback to finish	Hold the workflow at this node until the clip finishes playing

Use browser recording when you want to capture a short phrase without leaving Flow Designer. Preview the clip after you upload or record it so you can confirm the content and audio quality before you run.

Enable Loop playback when the app might not start listening immediately or when you need to repeat a phrase. Enable Wait for playback to finish when the next step depends on the full clip having played.

04Editing workflows

Use workflow settings to keep flow-level metadata current while you edit. In Flow Designer, open the workflow view in the Configure panel to update the workflow name, summary, description, status, and inputs from one place.

The Description field captures the purpose of the test and helps guide execution. Use it to explain what the workflow is validating, why the scenario matters, and any important intent that is not obvious from step names alone.

Flow Designer proposals now open in a side-by-side review experience so you can compare the current draft with the proposed workflow before you apply changes.

Use proposal review to inspect suggested changes before they affect your draft. This is especially useful when a proposal changes multiple branches or updates several nodes at once.

When you review a proposal, you can:

• Compare the current draft and the proposed workflow side by side
• Accept or reject proposal changes one node at a time
• Apply only the parts of a proposal you want to keep
• Undo accepted or rejected proposal decisions from the canvas history if you need to revisit them

If the proposal has changed elsewhere or someone already reviewed part of it, Flow Designer shows that state more clearly during review. Re-open the latest proposal state before you keep reviewing so you do not apply decisions to an outdated draft.

If a proposal is stale, refresh your review context and compare the current draft again before you accept or reject more nodes. If a proposal decision has already been made, review the current state first instead of trying to apply the same decision again.

If you accept or reject the wrong node, use the canvas history to undo that decision and continue reviewing. This lets you adjust proposal review without manually rebuilding the affected part of the flow.

When you multi-select nodes and delete them, Flow Designer removes the selected nodes together. In larger or more connected workflows, deletion can take a moment to complete.

Wait for the canvas to finish updating before making more edits. This helps you confirm that connected paths and remaining nodes have been updated correctly after the deletion.

If you are cleaning up a complex branch, delete in logical groups and review the graph after each change. This makes it easier to spot unintended path changes before you continue editing.

05Version history

Note: Workflow snapshots now show richer version details for both draft and published history. Use version history to review more context before you restore, compare, or publish.

Flows use a draft-and-published version model. Click the version selector in the header to open version history and switch between the Current draft, saved draft versions, named draft versions, and published versions.

Use version history to:

• Stay in the Current draft while you continue editing unpublished changes
• Save a draft checkpoint before making larger edits
• Give a draft version a clear name so it is easier to find later
• Open any draft or published version in read-only preview mode
• Review history banners, labels, and richer version details to confirm whether you are viewing the current draft, a draft snapshot, or a published snapshot
• Compare published and draft review context before you restore a version or continue editing
• Rename saved draft versions when you want clearer labels
• Restore a historical draft or published snapshot back into the current draft

A flow always has one editable Current draft. Saved draft versions and named draft versions are historical snapshots of that draft. Published versions remain immutable snapshots that stay available for runs, setup references, and historical review.

When you open anything other than the Current draft, Flow Designer switches to read-only preview mode. Use the banner at the top of the page to confirm what you are viewing and what actions are available.

Use these version labels to understand what you are viewing:

Label	Meaning
Current draft	The editable working version of the flow
Draft version	A saved draft checkpoint from earlier unpublished work
Named draft version	A saved draft checkpoint with a custom name
Published version	An immutable version that has been published
Quarantined	A workflow status that keeps the flow out of normal published regression coverage while preserving the workflow and its history

When you preview a historical version, review the banner before you act. The banner makes it clear that the version is read-only and helps you return to the Current draft or restore the snapshot into the draft.

Use Restore to Draft when you want to bring the contents of an older draft or published version back into the Current draft. This does not edit the historical snapshot itself. Instead, it creates a new state in your current draft that you can continue editing, testing, and publishing.

You can also rename saved draft versions to make checkpoints easier to recognize during longer editing sessions. Use clear names that describe the milestone or change you saved.

When a saved version includes setup nodes, version history shows a preview of the referenced setup flows in that snapshot. Use these previews to confirm prerequisite workflow context before you restore a version or compare it with your current draft.

Use the richer snapshot details to review draft and published context more confidently. For example, confirm whether you are looking at an unpublished checkpoint for active edits or a published snapshot that other flows or suites may still reference.

06Live Testing

Live Testing lets you test nodes incrementally while editing, without running the entire workflow each time.

1. Click Live Test in the header
2. A browser preview overlay appears
3. When you save a node, it executes automatically

Use Live Testing to verify macro-enabled fields as you edit. If a node or workflow field includes variables or macros, insert them with $ suggestions in the Configure panel, then save to confirm the step behaves as expected.

Reset behavior: If you edit a previously-tested node, the session resets to the nearest Login or Navigate node and re-executes from there.

Limitations:

• Cannot test past Wait nodes (use a full run instead)
• Sessions timeout after 10 minutes of inactivity

07Publishing

Note: Quarantined is now a first-class workflow status. Set it directly in workflow settings or from the Flows list when you want to keep an unstable workflow out of normal regression coverage without deleting it.

Publishing creates a new published version from the Current draft.

Before you publish, you can save draft checkpoints as often as needed and give them names that match milestones in your work. These draft versions stay in version history even after you continue editing or publish later.

A workflow status controls how teams treat the flow operationally:

Status	Meaning
Draft	The flow is still being edited and is not available as the active published workflow
Published	The flow is active and available for normal runs, setup references, and regression coverage
Quarantined	The flow is intentionally kept out of normal regression coverage while you preserve it for repair, review, or selective testing

Use Draft while you build or revise a workflow. Use Published when the flow is stable and ready for normal coverage. Use Quarantined when the workflow still matters but is too unstable, flaky, or temporarily out of scope for routine regression runs.

Action or state	Meaning
Draft	You are editing unpublished changes in the current draft
Run Flow	Run the current draft without changing its publish state
Ready to Publish	The latest run for the current draft passed and the draft is ready to publish
Publish	Create a new published version from the current draft
Published	A snapshot of the workflow is available as a published version
Quarantined	The workflow remains available in the workspace, but teams can exclude it from normal regression coverage

Continue editing in Draft while keeping the currently published version available for runs and references. Published versions do not change after publication, and new draft edits do not affect them until you publish again.

Use the publish button menu to choose the action you want. Click Run Flow when you want to test the current draft immediately without publishing it. Click Publish only when you want to create a new published version.

Before you publish, run the current draft and resolve any validation issues surfaced in the run flow experience. Then review the workflow summary card, confirm the workflow description still reflects the test intent, and confirm the latest run for the current draft passed. This helps ensure the draft is ready to publish.

If you restore an older draft or published snapshot, Canary places that content into your Current draft. Run the flow again if needed, then publish when the restored draft is ready.

Once published, the new version appears in version history with a published label and remains available for runs, setup references, and historical review. Draft checkpoints and named draft versions remain separate from published versions so you can keep iterating without losing earlier work.

If a published workflow becomes unreliable, change its status to Quarantined instead of deleting it. This keeps the workflow, run history, and version history available while removing it from normal regression expectations.

08Setup Nodes

Setup nodes let you run another published flow as a prerequisite before your main workflow. Use them for shared data creation or environment preparation.

When to use:

• Creating users, projects, or records that multiple tests depend on
• Setting up prerequisite data a workflow needs
• Environment preparation
• Pairing seed and teardown workflows for setup-heavy test scenarios

Login is handled separately via the Login node. Setup nodes are for data creation workflows.

Any published flow can be used as a setup step—there is no special "setup" publishing mode.

Use setup flows to prepare shared seed data, then add a teardown flow from the Seed Data page when you also need cleanup after the run.

Execution modes:

Mode	Behavior
Inline (default)	Runs before each workflow
Suite-level	Runs once per suite, shared across workflows

To use a setup node:

1. Publish the prerequisite flow (run it successfully, then click Publish)
2. Add a Setup node to your workflow
3. Select the published flow and version
4. Enable "Run once per suite" if the data should be shared across a test suite
5. If the setup creates seed data that must be removed later, add a teardown flow from the Seed Data page

09Replay and playback

Replay and playback show workflow progress step by step so you can review what ran, what produced data, and where execution changed.

Table extraction and Python execution now appear as first-class workflow actions in replay and playback. Instead of appearing only as part of a broader action, these steps show up directly in the timeline with their own entries.

Replay is now more resilient for difficult UI patterns and login-heavy workflows. Expect playback to follow recorded intent more reliably for icon-only controls, semantic class-based elements, and repeated row-based content.

When a workflow switches users during a run, review the replay timeline around each Login node to confirm where authentication changed. Login handling is more dependable, but explicit login steps still give you the clearest replay history when you troubleshoot user-specific behavior.

Use timeline visibility to:

• Confirm when a table extraction step ran during the workflow
• See when Python execution happened relative to page actions and assertions
• Review workflow history with clearer step-by-step context during debugging
• Confirm when an Audio Input node started playing a clip and whether the workflow continued immediately or waited for playback to finish
• Check how Canary targeted a repeated row or control when you investigate a replay difference
• Verify where a user switch happened in a multi-user workflow

When you inspect a run, look for these actions in the timeline alongside the rest of the workflow steps. This makes playback easier to follow when your flow mixes browser interactions with data extraction, Python-based logic, or microphone input.

10Importing flows

You can create workflow drafts from several import entry points:

Import source	What it does
CSV	Turns structured test case data into a draft workflow
Test file	Converts an existing test file into a draft workflow
Jira ticket	Searches Jira issues, generates a suggested testing goal and context, and opens the result in the workflow builder

Use imports when you want to start from existing test assets or planning work instead of building every step by hand.

When you import from a Jira ticket, search for the issue you want, review the suggested testing goal and context, and then open the generated draft in Flow Designer. Use the builder to refine the generated steps before you run or publish.

When you import a flow from CSV or convert a test file, review the imported draft before you publish it. The importer separates preconditions from executable workflow steps more reliably, so imported flows better match the structure of the source test case.

CSV imports also avoid inventing login details. If the source material does not include clear login information, add or update the Login node yourself after import instead of assuming credentials were created for you.

Imported flows now wait for validation runs to succeed before auto-publishing. If the imported draft has unresolved validation issues, complete the required configuration and run the flow successfully before you publish it.

After import, check these areas:

• Confirm that preconditions appear as setup context instead of executable steps where appropriate
• Review any generated Login step and replace or complete it with the correct credential
• Review the suggested testing goal and context if the draft came from Jira, then update them to match the scenario you want to automate
• Add or refine the workflow description so it explains the scenario purpose and intended outcome before you run
• Resolve validation feedback before you expect the flow to publish automatically
• Run the imported draft to confirm the executable steps reflect the intended workflow

All import paths create a draft that feeds directly into Flow Designer. Treat the generated workflow as a starting point, then use the workflow builder to update nodes, configure variables, and validate the run before publishing.

11Best practices

• Use workflow inputs for values that change between runs, such as account IDs, email addresses, dates, or environment-specific data.
• Review the workflow summary card before you run or publish so you can confirm the flow-level configuration at a glance.
• Add a workflow description that explains the purpose of the test, the user outcome you expect, and any important business context that should guide execution.
• Keep the workflow description focused on intent, not step-by-step instructions. Use node names and node configuration for the detailed actions.
• Update the workflow description whenever the workflow goal changes so the metadata stays aligned with the authored steps.
• Use root-relative paths such as /settings in Navigate nodes when you want the same flow to work across multiple environments.
• Use variables or macros in Navigate node URLs when part of the path changes between runs, and verify those values are available before the node executes.
• Prefer absolute URLs only when the destination must stay fixed to a specific domain.
• When you record a workflow, review generated steps for icon-only controls, repeated rows, and other visually similar elements before you publish.
• Make action descriptions specific when a step targets content inside a list, table, or repeated row. Include the row context or identifying text so replay stays easier to understand.
• For keyboard-driven interactions, make sure the workflow first opens, selects, or clearly targets the field or control that should receive focus before you type or send keys.
• If you use keyboard shortcuts or submit keys such as Enter, keep the preceding step focused on the same input or control so key entry stays reliable.
• Keep form-entry steps focused when later steps depend on typed values. This makes focus handling and replay easier to follow.
• Use AI-generated values in supported step inputs when you need realistic one-off text instead of a hardcoded string.
• If a later step depends on an AI-generated value, reference that produced value instead of duplicating or manually re-entering it.
• Add explicit Login nodes wherever the workflow changes user context. This keeps multi-user flows easier to replay, debug, and maintain.
• Use credential templates in Login nodes when the same flow needs to run across different accounts or environments.
• Re-add a Login node after a Wait node to re-establish the browser session before the workflow continues.
• Review the default 30 minutes delay whenever you add a Wait node, and update it if the workflow should resume at a different time.
• After a Wait node, confirm that later steps reference the workflow inputs or outputs you expect to carry forward into the resumed segment.
• Place Notification nodes after the steps that produce the information or files you want to send.
• Use Notification nodes for workflow-driven emails, and keep the subject and body specific so recipients can act quickly.
• For voice or microphone testing, place Audio Input nodes only after the browser experience is ready to listen.
• Preview recorded or uploaded audio before you run so you can catch clipping, silence, or the wrong phrase early.
• Use Loop playback only when the listening window may start late or remain open long enough to need repeated audio.
• Enable Wait for playback to finish when later steps depend on the full clip being delivered before the workflow continues.
• Review validation feedback before you run, especially for unresolved variable references, notification outputs that are referenced too early, disconnected nodes, or environment selection defaults.
• Use validation runs to test brand-new workflows that have never passed before, then switch to normal iteration after the first passing run.
• During a validation run, expect Canary to keep going through reasonable ambiguities so you can uncover more issues in one pass.
• Use warning-level assertions for non-blocking checks that still matter to the workflow.
• Confirm whether you are editing the Current draft or previewing a historical version before making changes.
• Use named draft versions for major checkpoints so version history stays easier to scan.
• When reviewing older versions, check the history banner and setup flow previews before you restore a snapshot.
• Use Quarantined for workflows that are temporarily unstable, flaky, or under repair but should remain available for selective testing and historical review.
• Do not delete a workflow just to remove it from routine regression coverage. Change its status to Quarantined instead.
• Return quarantined workflows to Published only after you validate the latest draft and confirm the workflow is stable again.
• If a published flow is repeatedly failing in suites, monitor whether Canary marks it as degraded and skips it from future suite runs until you fix or re-enable it.
• Re-enable degraded flows from Flow Designer after you address the root cause and want the flow included in suites again.
• When deleting multiple nodes, work in small groups for complex workflows and confirm the canvas updates before continuing.
• Review proposals side by side before you accept changes into the current draft.
• If proposal review shows a stale or already-decided state, refresh the review context before you keep applying decisions.
• Use per-node accept and reject decisions when only part of a proposal should be applied.
• If you change a proposal decision by mistake, use canvas history to undo it instead of rebuilding the node manually.

12Running workflows

When you run a workflow, fill in any workflow inputs before you start the run. Use these inputs to parameterize the workflow without editing step configuration for each variation.

For example, define workflow inputs for values such as a user email, account ID, search term, or date range, then provide the run-specific values at run time.

Flow Designer now uses two pre-run behaviors depending on the state of the workflow:

Run type	When Canary uses it	What to expect
Validation run	The workflow has never had a passing run	Canary keeps going through reasonable ambiguities so you can surface more authoring and execution issues in one run
Normal run	The workflow has already passed at least once	Canary uses standard execution behavior for ongoing testing and iteration

A validation run helps you test a brand-new workflow more effectively, including workflows imported or authored from scratch that have never passed before. Instead of stopping at the first reasonable uncertainty, Canary continues where it can so you can uncover more issues in a single run.

Use a validation run when you want to:

• Test a newly created or newly imported workflow that has not passed yet
• Surface multiple authoring issues before you start iterating on fixes
• Check whether the overall path is viable before you publish

Once the workflow has a passing run, later runs use the normal run mode. Normal runs prioritize standard execution behavior rather than broad issue discovery.

Flow Designer still defers most validation until you click Run Flow. Before the run starts, Canary now checks the draft more accurately so you can fix common problems earlier in the run flow experience.

Before a run starts, review warnings and errors for issues such as:

• Missing required workflow inputs or incomplete step configuration
• Variable, macro, or workflow input references that cannot be resolved
• Notification outputs that are referenced before the Notification node can produce them
• Disconnected nodes that are not part of the executable path
• Environment selection issues, including cases where Canary can apply the default environment automatically

If validation feedback shows that a required input, variable reference, or step configuration is incomplete, resolve it before you run. This keeps editing quieter while still preventing invalid runs from starting.

During execution, assertion outcomes are handled more clearly in the run timeline and results. Review each assertion step in the run to confirm whether it passed, produced a warning, or failed the workflow.

If your workflow includes an Audio Input node, Canary plays the configured clip into the browser microphone when the run reaches that step. If Wait for playback to finish is disabled, the workflow can continue while the clip is still playing. If Wait for playback to finish is enabled, the run pauses at that node until playback completes.

Use Loop playback when the target experience may begin listening slightly after the node starts. If you do not need repeated audio, leave looping off so the clip plays once.

If your workflow includes a Wait node, the run pauses for the configured delay before resuming automatically. New Wait nodes start with a default delay of 30 minutes, so review that value before you run if you recently added the step.

If your workflow includes steps that encounter a captcha, expect the run to surface that step more clearly in the run results. Use the step details to identify where the captcha appeared and decide whether to update the workflow path, test data, or environment setup before you run again.

If you select multiple workflows and use Run selected, Canary dispatches each selected workflow as its own run. Expect each valid workflow to start separately rather than as one combined execution.

If one selected workflow has validation issues, review that workflow and fix it before you try again. Other selected workflows that pass validation can still be dispatched normally.

13Flows list

Use the Flows page to browse all workflows in your workspace. The list shows each flow as a row, so you can scan names, status, and other metadata before you open a draft or published version.

From the list, you can sort, search, and narrow what you see before you open a flow. Use filters when you want to focus on a smaller set of workflows without changing the underlying flows.

You can also change workflow status directly from the list. Use list actions when you need to quarantine or restore several workflows without opening each one individually.

14Filtering and discovery

Use filters on the Flows page to find workflows faster.

Filter	Use it for
Author	Show only flows created by a specific teammate
Status	Show only workflows in a specific workflow status, such as Draft, Published, or Quarantined

Use the Author filter when you want to review flows owned by a particular person, hand off work, or find workflows that one teammate created.

Use the Status filter when you want to focus on active regression coverage, review quarantined workflows that need repair, or separate unpublished work from stable published flows.

Combine filters with search or sorting when you need to narrow a large workspace quickly. Clear the filter to return to the full list.

15Flow Designer behavior

Flow Designer opens the editor that best matches the flow.

If a flow is built entirely around API steps, Canary opens it in API view by default. This helps you land in the editor and run context that matches how the flow is authored.

If a flow includes browser-based steps, Canary continues to open it in the standard visual designer. Switch views only when you need to inspect or edit the flow differently.

16Variables and dynamic data

Use workflow inputs, variables, and macros to make a flow reusable across environments and run scenarios.

Use workflow inputs for values you know at run time, such as emails, IDs, search terms, or date ranges. Use variables and macros when values come from earlier steps or shared context in the workflow.

Before a run starts, Canary checks whether each referenced value can be resolved. If a Navigate node, Action node, or other step contains an unresolved reference, fix the missing input or update the reference before you run.

Pre-run validation is especially useful when you:

• Reuse the same flow across multiple environments
• Pass IDs or tokens between steps
• Build URLs or messages with workflow inputs and macros
• Run several selected workflows at once and want to catch configuration issues early

You can also use AI-generated values directly in supported step inputs. This is useful when the flow needs realistic dynamic content such as names, subjects, or short free-text entries.

If a later step needs to reuse a generated value, reference that value in the next step instead of copying the text manually. This keeps validation and run behavior aligned with what the workflow actually produced.

Validation is also more accurate for variable references across waits and resumed segments. If a step depends on data created before a Wait node, confirm the later reference points to the right workflow input, variable, or step output.

To avoid unresolved references:

• Define each workflow input before you use it in a step
• Confirm variable names match exactly where you reference them
• Review validation warnings in Flow Designer before you publish
• Check run-time input values before you click Run Flow
• Re-check dynamic references after you add or move a Wait node in the path

17Troubleshooting

Issue	What to check
A workflow does not start	Review the run dialog for unresolved variable references, missing required inputs, incomplete step configuration, or environment selection issues
A recorded step replays the wrong element	Review whether the step targeted an icon-only control, semantic element, or repeated row. Update the step description so the intended element or row context is clearer, then run again
A Navigate node opens the wrong destination	Confirm the URL format and verify that any variables or macros in the path resolve at run time
A selected bulk run starts fewer workflows than expected	Check whether any selected workflows have validation errors that prevent those individual runs from starting
A setup workflow cannot be selected	Confirm that the referenced flow has been published
A published flow cannot be edited	Return to the Current draft from version history
A proposal review shows a stale or already-decided proposal	Re-open the latest proposal state, review the current draft again, and then continue accepting or rejecting nodes
A proposal review applied the wrong change	Use canvas history to undo the accept or reject decision, then review the proposal again
An assertion step caused unexpected run behavior	Check the assertion severity and review the step outcome in Run details to see whether the assertion passed, warned, or failed
A workflow behaves unexpectedly after switching users	Confirm that the flow includes an explicit Login node where the user context should change, and check replay around that step to verify the switch happened at the right point
A Wait step resumes at the wrong time	Confirm the configured delay in the Configure panel. New Wait steps default to 30 minutes, so update the delay if you intended a different pause length
A form step types into the wrong field or a keyboard shortcut affects the wrong control	Confirm that the previous step opened or selected the intended field or control before key entry, then make the step description more specific if needed
An Audio Input step does not behave as expected	Confirm that the correct clip is attached, preview it in the editor, and check whether Loop playback or Wait for playback to finish matches the scenario
A run stops or behaves unexpectedly around a captcha	Open the run step details to confirm where the captcha appeared, then update the workflow path, test data, or environment setup before you retry
A Jira import does not produce the right workflow	Review the suggested testing goal and context in the generated draft, then refine the steps in Flow Designer before you run or publish
A converted test file or CSV import is missing setup or login details	Add or update the generated Setup or Login nodes in the draft before you validate the workflow
A flow is missing from a suite run you expected it to join	Check whether Canary marked the flow as degraded and skipped it from the suite
A degraded flow should run in suites again	Open the flow in Flow Designer, re-enable it, and then run the suite again after you confirm the fix
A run is hard to trace back to the authored flow	Use the run debug view and Run details to compare step timing, failure hints, trace links, and the authored workflow steps side by side
An API-only flow opens in the wrong editor	Re-open the flow and confirm that the flow is built entirely from API steps. Mixed flows continue to open in the standard visual designer
A flow list filter hides workflows you expect to see	Clear the Author or Status filter, or choose a different value to return more results
A workflow should stay in the workspace but not run as part of normal regression coverage	Change its status to Quarantined from workflow settings or the Flows list instead of deleting it

If a run is blocked before it starts, resolve the validation issue shown in the run dialog first. Most blocked runs are caused by missing workflow input values or references that no longer match a defined variable.

Validation feedback is also more specific before execution begins. If Canary warns about a disconnected node, reconnect it or remove it so the intended path is executable. If Canary flags a notification output reference, confirm that the workflow reaches the Notification node before any later step tries to use that output.

If a run can use the default environment automatically, review the selected environment before you continue. If the wrong environment is selected, change it explicitly in the run flow experience.

If a recorded or authored step keeps choosing the wrong control, make the step goal more specific and include the visible context that distinguishes the target. This is especially helpful for icon-only buttons, repeated rows, and similar page patterns.

If an assertion outcome is not what you expected, confirm whether the step was configured as Fail or Warn before you interpret the run result. Warning-level assertions let the workflow continue, while fail-level assertions stop the run at that step.

If a workflow changes users during login, inspect the replay timeline around each Login node first. Confirm that the right credential or credential template is selected, then run the workflow again after you adjust the login boundary if needed.

If a Wait step pauses longer or shorter than you expected, open the step in the Configure panel and verify the configured delay. Review new Wait nodes carefully because they start with a 30 minutes default delay.

If a form step or keyboard-driven interaction affects the wrong place on the page, review the step immediately before key entry. Make sure the workflow clearly leaves focus in the intended field or control, then run again after you tighten the step description.

If a resumed flow does not seem to have the data you expect after a Wait node, review the variable or step-output references in the resumed steps first. Then confirm that the step producing the value ran before the wait and that the later step references the correct dynamic value.

If an Audio Input step does not trigger the expected app behavior, make sure the workflow reaches that node only after the app is actively listening for microphone input. Then preview or replace the clip and adjust looping or wait behavior before you run again.

If a captcha interrupts the workflow, inspect the run details to find the affected step first. Then adjust the scenario so the workflow can avoid or handle that captcha path more reliably in future runs.

For bulk runs, review each selected workflow if some runs start and others do not. Canary dispatches selected workflows individually, so validation issues in one workflow do not change the expected behavior of other valid selections.

If a flow does not appear in a suite run, review the suite summary and the flow status. Degraded flows are skipped from future suite runs until you re-enable them.

If you fixed a degraded flow, open it in Flow Designer and re-enable it before you expect it to run in suites again.

If a proposal review changes the wrong node, undo the last proposal decision from canvas history and then continue reviewing the remaining nodes.

If an imported workflow needs more refinement, treat the generated draft as a starting point. Update the testing goal, context, description, steps, and credentials in Flow Designer, then run the draft again before you publish.

If an API-only flow does not open in API view, confirm that the flow is still API-only and does not include browser-based steps. If you filtered the Flows list and cannot find a workflow, clear the active filter and search again.

18Debugging and iterating on flows

Use the run debug view to investigate failures and decide what to change in the authored workflow. The debug view consolidates step timing, cache details, failure hints, thought summaries, and trace links in one place so you can move from run investigation back to editing faster.

When you inspect a failed or unexpected run:

1. Open the run from the workflow or run history
2. Review the failing step and compare it with the authored step in the workflow
3. Check timing, cache details, and failure hints to understand what happened at run time
4. Open trace links or step details when you need deeper evidence
5. Return to the flow draft and update the specific step, input, or login configuration
6. Run the workflow again to confirm the change

Use this workflow to connect authored steps and run evidence more clearly:

• Keep step names specific so they are easier to recognize during debugging
• Review step-level timing when a run slows down or stalls
• Check cache details before assuming the agent evaluated fresh state
• Use failure hints to narrow the likely cause before you edit multiple steps
• Follow trace links when step details alone do not explain the failure
• If the flow is degraded, fix the repeated failure pattern before you re-enable it for suites

If the problem starts at authentication, review the Login node first. Confirm whether the step should use a saved credential or a credential template, then run the flow again after you update it.

For step-by-step investigation, use Run details. Use replay and playback when you want timeline context across the full workflow.

19Workflow runs

Workflow runs now surface more pre-run and in-run context so you can understand how Canary prepared the execution and what the agent saw before the first step.

Run details can include an Agent briefing generated from your property's knowledge graph. Use this briefing to review product terminology, app structure, and other relevant context that Canary provided to the agent before the workflow began.

Use the Agent briefing when you want to:

• Understand the context Canary used before execution started
• Check whether the workflow had relevant product or navigation guidance
• Troubleshoot why the agent interpreted a page or step a certain way

The briefing complements the rest of the run record. Review it alongside the timeline, step details, and assertion outcomes in Run details when you debug a workflow.

20Workflow health and execution behavior

Canary now tracks flow reliability over time. If a published flow fails repeatedly, Canary can mark it as degraded and exclude it from future suite runs until you fix it or re-enable it.

A degraded flow helps keep suite results focused on flows that actually ran. Canary still preserves the flow, its history, and its run details so you can investigate the problem and decide when to return it to normal suite coverage.

Use degraded flow behavior when you want to:

• Prevent repeatedly failing flows from creating noise in recurring suites
• Keep suite pass and fail counts focused on executed flows
• See which unstable flows need repair before you include them in regression coverage again

When a flow is degraded:

Behavior	What happens
Future suite runs	Canary skips the flow automatically
Flow summaries	Canary shows the flow as degraded where supported
Suite summaries	Canary shows degraded totals separately from executed results
Flow Designer	You can re-enable the flow after you fix it

If you need to return a degraded flow to suite coverage, open the flow in Flow Designer, review the recent failures, make the needed changes, and then re-enable it.

After you re-enable the flow, run it again to confirm the fix before you rely on it in suites.

21Related

• Canary Recorder Extension
• Credentials and Login
• Designing a good test
• Jira
• Run details
• Seed Data
• Suites
• Variables
• Workspaces