Help & Documentation

Everything you need to know about creating, running, and monitoring your QA flows.

Creating Flows

A flow is a sequence of steps that represent a user journey (e.g. login, checkout, signup). There are three ways to create flows:

Chrome Extension

Record your actions in the browser and save them as a flow automatically.

Import from File

Upload a CSV (with full selectors) or a Gherkin-style text file.

Manual Creation

Add steps one by one using the inline editor on the flow page.

Chrome Extension

Install the HorusQA Chrome Extension

The extension records your browser interactions and sends them to HorusQA as replayable test steps.

Download from Chrome Web Store

How it works

  1. Click the HorusQA extension icon in Chrome and log in with your API token.
  2. Select the project and give your flow a name.
  3. Click 'Start Recording' and navigate through your application normally — every click, form input, and page navigation is captured.
  4. Right-click any element to add assertions (check text, visibility, values, etc.).
  5. Click 'Stop Recording' — the flow is saved and ready to run.

Adding assertions

While recording, right-click any element to open the assertion menu. You can assert that text is visible, an element exists, a field has a specific value, or the URL/title matches a pattern.

Selector strategy

The extension captures multiple selectors for each element, ordered by reliability. During replay, each selector is tried in order until one works:

1. data_testid 2. id 3. name 4. css_class 5. text 6. xpath

Importing Flows

You can import flows from CSV or Gherkin-style text files. Use the Import button on the project page.

Manual Step Creation

You can build flows step by step using the inline editor at the bottom of the steps table on any flow page.

  1. Open a flow and scroll to the steps table.
  2. Select the action type from the dropdown (visit, click, fill_in, etc.).
  3. Enter the target selector (CSS, ID, name, etc.) and value if needed.
  4. Click '+' to add the step. Drag steps to reorder them.

Step Types

Actions

Visit URL

Navigate to a URL. This is typically the first step in a flow.

Click

Click on an element identified by a selector.

Fill in

Type text into an input field or textarea.

Submit

Submit a form.

Select Option

Select an option from a dropdown / select element.

Check

Check a checkbox.

Uncheck

Uncheck a checkbox.

Accept Alert

Accept a browser alert / confirm dialog.

Dismiss Alert

Dismiss a browser alert / confirm dialog.

Scroll

Scroll the page to bring an element into view.

Assertions

Assertions verify that your application is in the expected state. If an assertion fails, the run is marked as failed.

Assert Text

Verify that specific text appears on the page.

Assert Visible

Verify that an element is visible on the page.

Assert Hidden

Verify that an element is NOT visible on the page.

Assert Value

Verify that an input field contains a specific value.

Assert URL

Verify the current URL matches the expected value.

Assert Title

Verify the page title matches the expected value.

Assert Exists

Verify that an element exists in the DOM (even if hidden).

Dynamic Placeholders

Use placeholders in step values to generate unique data on every run. Perfect for testing registration forms, unique fields, or any input that rejects duplicates.

Placeholder Description Example Output
{{random_email}} Unique email address test_a1b2c3d4_1714423200@horusqa.test
{{random_name}} Random username User_a1b2c3d4
{{random_number}} 5-digit random number 47382
{{random_phone}} Random US phone number +12345678901
{{random_password}} Secure password (uppercase, symbol, digits) Hq!a1b2c3d4e587
{{random_text}} Random alphanumeric string a1b2c3d4e5f6
{{uuid}} UUID v4 identifier 550e8400-e29b-41d4-a716-446655440000
{{timestamp}} Unix timestamp (seconds) 1714423200

The same placeholder resolves to the same value across all steps in a single run. For example, if two steps use {{random_email}}, both will receive the same generated email — useful for 'email' and 'confirm email' fields.

Example: Registration Form

A flow that tests user signup with unique data on every run:

fill_in name="email" {{random_email}}
fill_in name="name" {{random_name}}
fill_in name="pass" {{random_password}}
fill_in name="confirm" {{random_email}}

Both {{random_email}} steps will use the same generated email within this run.

Mixing with Text

Placeholders can be combined with literal text in the same value:

Order #{{random_number}} — {{random_name}}

Triggering Runs

There are four ways to trigger a flow run:

Manual

Click 'Run Now' on any flow page or from the project dashboard.

Scheduled

Configure a schedule (every 15min to weekly) on the flow edit page. Runs are dispatched automatically while respecting plan limits.

API

Trigger a run via the REST API. Create an API token in Settings > API Tokens.

curl -X POST https://horusqa.ai/api/v1/flows/:id/run \
  -H "Authorization: Bearer YOUR_TOKEN"

GitHub Webhook

Configure a GitHub webhook to trigger runs on push or pull request events. See the API documentation for the webhook endpoint.

Running Against Different Environments

Record a flow once and run it against any environment — staging, production, or your local machine via ngrok.

URL Override

When triggering a run, use the 'Override URL' field to replace the original domain in all step URLs. Leave it empty to use the URLs as recorded.

If your flow was recorded on https://staging.mysite.com and you enter https://mysite.com as the override, all steps will run against production.

API Override

When triggering runs via the API, pass the base_url_override parameter:

curl -X POST https://horusqa.ai/api/v1/runs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"flow_id": 123, "base_url_override": "https://abc123.ngrok-free.app"}'

Testing Locally with ngrok

ngrok creates a public tunnel to your local development server, letting HorusQA reach your machine.

  1. Install ngrok from ngrok.com and authenticate with your free account.
  2. Start your local dev server (e.g. on port 3000).
  3. In a separate terminal, run: ngrok http 3000 
    ngrok http 3000
  4. Copy the Forwarding URL (e.g. https://abc123.ngrok-free.app).
  5. Paste that URL in the Override URL field and click Run Now.

Your ngrok URL changes each time you restart the tunnel (unless you have a paid plan with a fixed domain).

Notifications & Integrations

Get notified when runs complete. Configure integrations in your project's Integrations page.

How runs deal with slow pages

Every step is tried up to three times. The second attempt waits for the page to finish loading; the third also waits for network activity to settle and scrolls the page. Most timing problems on slow staging environments resolve themselves this way.

A step that only passed on a retry shows an amber warning icon in the run. If a flow shows it often, the app is slow at that point, not flaky.

When to Notify

Each integration can be configured to notify on specific run outcomes. By default, notifications are sent for failed and error runs only.

Failed

A step assertion failed. The test detected a problem in your application.

Error

The run could not complete — timeout, browser crash, or infrastructure issue.

Passed

All steps passed. Enable this for full visibility or audit trails.