> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/execution/regression-suite-tutorial.md).

# Tutorial: Build and Schedule a Regression Suite

{% hint style="info" %}
**Who is this for?** Testers, SDETs, and QA managers who have created a few test cases and want to run them together, on a schedule, as a continuous regression check. You connect the building blocks — test cases, a suite, a test plan, and a schedule — into one automated workflow.
{% endhint %}

Individual test cases tell you whether one flow works right now. A regression suite tells you whether your whole application still works after every change — automatically, overnight, without anyone clicking **Run**. This tutorial takes you from a set of existing test cases to a nightly regression run that posts results to Slack.

In this tutorial you will:

1. Group related test cases into a test suite
2. Build a test plan that targets a browser and an environment
3. Run the plan manually to confirm it works
4. Schedule the plan to run automatically every night
5. Review continuous results and route failures to Slack

**End result:** A regression test plan that runs your suite every night against your staging environment and alerts your team in Slack when something breaks.

## Prerequisites

* A ContextQA account with a workspace ([sign up](https://accounts.contextqa.com/onboard))
* At least three test cases that pass when run individually (see the [Quick Start guide](/getting-started/quickstart.md) to create them)
* An [environment](/execution/environments.md) configured with the base URL of the application you want to test
* Optional: a connected Slack workspace for failure notifications (see the [Slack integration](/integrations/slack.md))

{% hint style="info" %}
Run each test case once on its own before adding it to a regression suite. A suite built from already-passing tests gives you a clean baseline, so the first failure you see is a real regression rather than a setup problem.
{% endhint %}

***

## Step 1: Group your test cases into a suite

A test suite is a named group of test cases that run together as a unit. It's the layer between individual test cases and the test plan that executes them.

1. In the left sidebar, click the **Test Development** icon.
2. Open the **Test Suites** tab.
3. Click **+ Create Test Suite**.
4. Fill in the suite form:
   * **Suite Name** — use a pattern that signals scope and type, such as `Regression_Checkout`. A consistent name keeps the suite readable in test plan dropdowns and report headers.
   * **Description** — note the feature area covered and the environment this suite targets.
   * **Parent Suite** — leave empty for your first suite.
5. Click **Create Suite**.

Now add your test cases:

1. Open the new suite by clicking its name.
2. Click **Add Test Cases**.
3. Search for each test case by name, or filter by tag. Select the test cases you want to include.
4. Click **Add Selected**.

**Verify:** The suite now lists every test case you added. The order shown is the order in which the tests run when the suite executes sequentially — drag the handle (⋮⋮) on any row to reorder.

{% hint style="info" %}
Keep a regression suite focused on one feature area and under 50 test cases for fast, debuggable runs. For larger libraries, nest sub-suites under a parent suite. See [Managing Test Suites](/web-testing/managing-test-suites.md) for nesting and naming conventions.
{% endhint %}

***

## Step 2: Build a test plan

A test plan is the execution configuration: it specifies which suites to run, which browser or device to target, which environment to use, and how the run behaves on failure. ContextQA creates a test plan through a three-step wizard.

1. Open the **Test Plans** tab in Test Development.
2. Click **Create Test Plan**.

The wizard opens on the first step.

### Create Test Plan

Configure the plan basics:

* **Test Plan Name** — name it for its purpose and target, such as `Regression — Checkout — Staging`.
* **Environment** — select the environment whose base URL the tests run against. Choose your staging environment.
* **Test plan type** — select **Cross Browser Testing** for a web suite. (Choose **Cross Device Testing** only for mobile suites.)

Click **Next**.

### Test Machines & Suites Selection

On the second step, choose what runs and where:

1. Under **Select Browser**, pick a browser (for example, Chrome), then set the **Browser Version** and **Resolution**.
2. Under **Selected Test Suites**, add the regression suite you created in Step 1.
3. Set the suite execution behavior:
   * **Run Test Suites in Parallel** — enable this to run independent suites at the same time for speed. Leave it off if suites must run in order.
   * **Reset Session for Every Test Case** — enable this so each test case starts from a clean browser session, which prevents one test's state from leaking into the next.

Click **Next**.

### Test Plan Settings

On the final step, configure how the run handles failures:

* Under **Recovery Actions**, set **Rerun on failure** if you want ContextQA to automatically retry a failed test case once before reporting it as failed. This filters out transient flakiness in scheduled runs.
* Review the remaining recovery options for prerequisite and aborted-test handling, then adjust them to match your team's tolerance for partial runs.

Click **Save** (or **Create Test Plan**) to finish.

**Verify:** The new plan appears in the **Test Plans** list with the name you gave it.

***

## Step 3: Run the plan manually

Always confirm a plan runs cleanly by hand before you schedule it. A scheduled plan that has never passed only automates uncertainty.

1. In the **Test Plans** list, open your regression plan.
2. Click **Run** to trigger the execution.

ContextQA queues the run and executes each test case in the suite on the browser and environment you configured. As the run progresses, you see per-test pass/fail status in real time.

**Verify:** When the run completes, every test case shows a green pass indicator. Open the execution report to confirm the screenshots, video, and per-step results match your expectations.

{% hint style="warning" %}
If a test fails here, fix it before scheduling. A failing test in a manual run fails on every scheduled run too, producing alert noise that trains your team to ignore notifications. See [How to Debug a Failing Test](/reporting/debugging-failing-tests.md).
{% endhint %}

***

## Step 4: Schedule the plan

With a passing manual run as your baseline, set the plan to run automatically.

1. Open your regression plan and click the **Schedules** tab.
2. Click **+ Add Schedule**.
3. Configure the schedule:
   * **Schedule Name** — describe the timing and purpose, such as `Nightly Regression — Staging`.
   * **Frequency Type** — select **Preset** and choose **Daily**, or select **Cron Expression** for precise control.
   * **Cron Expression** (if selected) — enter `0 1 * * *` to run at 1:00 AM every night.
   * **Timezone** — set this to your team's local timezone so the run lands when you expect it. A cron of `0 1 * * *` in UTC isn't 1:00 AM where your team works.
   * **Active** — leave this toggled on.
4. Click **Save Schedule**.

**Verify:** The schedule appears in the **Schedules** tab with its next scheduled run time displayed.

{% hint style="info" %}
Run a full regression suite nightly so every morning starts with a clear picture of application health. Pair it with a lighter smoke suite scheduled hourly (`0 * * * *`) to catch deployment breakages within the hour. See [Scheduling Tests](/execution/scheduling.md) for cron examples and scheduling hygiene.
{% endhint %}

***

## Step 5: Route failures to Slack

Overnight runs only help if a failure reaches the right people before work starts.

1. Open your regression plan and click the **Settings** tab.
2. Under **Notifications**, enable **Slack**.
3. Select the Slack channel to notify, such as `#qa-daily-report`.
4. Set the notification trigger:
   * **On failure only** — recommended for most teams. ContextQA sends a Slack message only when a scheduled run has at least one failed test case.
   * **Always** — sends a message for every run, pass or fail.
5. Save the plan settings.

**Verify your notification setup:** Temporarily edit one test case to assert something false, let the next scheduled run execute (or trigger a manual run), and confirm the Slack message arrives with the plan name, pass/fail counts, and a link to the report. Revert the test case afterward.

***

## Summary

You have turned a set of standalone test cases into a continuous regression check. You:

* Grouped related test cases into a named test suite
* Built a test plan targeting a browser and a staging environment
* Confirmed the plan passes with a manual run
* Scheduled the plan to run automatically every night
* Routed failures to Slack so your team learns about regressions immediately

Your application is now monitored on a recurring schedule, and the self-healing AI handles most minor UI changes automatically — so the failures that reach Slack are the ones worth investigating.

## Next steps

* [Parallel Execution](/execution/parallel-execution.md) — run large suites faster by executing test cases simultaneously
* [Configuring Environments](/execution/environments.md) — add staging and production environments so one plan can target each
* [Flaky Test Detection](/reporting/flaky-test-detection.md) — identify tests that fail intermittently and erode trust in your suite
* [Analytics Dashboard](/reporting/analytics-dashboard.md) — track pass rates and trends across scheduled runs
* [GitHub Actions Integration](/integrations/github-actions.md) — trigger the same plan from your CI/CD pipeline on every pull request

## Troubleshooting

**A test case I added to the suite isn't appearing** Refresh the page — the suite test case list updates asynchronously. Confirm no active filter in the test case picker excluded it.

**The plan ran but skipped a suite** Open the plan's **Test Machines & Suites Selection** step and confirm the suite is listed under **Selected Test Suites** and assigned to a browser.

**The scheduled run didn't execute at the configured time** Check the schedule's **Timezone**. A cron of `0 1 * * *` set to UTC runs at 1:00 AM UTC, not 1:00 AM local. Also confirm the schedule's **Active** toggle is on.

**Slack notifications aren't arriving** Confirm the Slack integration is connected in workspace **Settings → Integrations → Slack** and that the ContextQA app still has permission to post to the selected channel.

## Related pages

* [Managing Test Suites](/web-testing/managing-test-suites.md)
* [Scheduling Tests](/execution/scheduling.md)
* [Running Tests](/execution/running-tests.md)
* [Configuring Environments](/execution/environments.md)
* [Quick Start guide](/getting-started/quickstart.md)

{% hint style="info" %}
**10× faster with parallel execution across browsers and devices.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See ContextQA run your full regression suite on a schedule.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://learning.contextqa.com/execution/regression-suite-tutorial.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.