# How to Schedule Automated Test Runs

:::lead
Schedules run your Test Suites or Test Cases automatically — once, or on a repeating pattern — so your regression checks happen without anyone clicking **Run**.
:::

Open **Schedule Runs** from the sidebar to create and manage schedules for your project.

:::info{title="Scheduled runs use the Cloud"}
Every scheduled run executes on TestOwl's cloud infrastructure, so nobody needs to keep a computer or the Desktop App open. Scheduled runs count towards your plan's **cloud** execution quota. See [Plans & Usage](/docs/team-and-account/plans-and-usage).
:::

## The Schedule Runs page

The page opens with two summary cards:

- **Total Schedules** — with a breakdown of how many are active and how many are paused.
- **Upcoming Runs** — how many occurrences are queued to be dispatched.

Below them, the schedule list shows each schedule's **Name**, **Recurrence**, **Next Run**, **Status**, **Created At**, and **Created By**. You can:

- Search by name.
- Filter by **Status** (Active, Paused, Completed) and by **Repeats** (Once, Interval, Weekly, Monthly, Custom dates).
- Sort the list.
- Select several schedules and use **Pause** or **Resume** in the toolbar to change them all at once.

## Creating a schedule

1. Click **New Schedule**.
2. Fill in the three sections of the drawer, described below.
3. Click **Create Schedule**.

### General

| Field | Description |
| --- | --- |
| **Schedule Name** | A name your team will recognise, such as `Nightly Regression`. Up to 200 characters. |
| **Environment** | One or more [Environments](/docs/environments/overview). If you select several, each occurrence starts one run per environment, exactly like a manual run. |
| **URL** | The web address of the application to test, for example `https://staging.example.com`. |
| **Tests in parallel** | How many tests in each occurrence run at the same time. Capped by your plan's parallel-worker limit. |

### What to run

Use the switch at the top of this section to choose what the schedule runs:

- **Test Suites** — runs every runnable test inside the selected suites. Tests you add to those suites later are picked up automatically.
- **Tests** — runs only the individual Test Cases you tick, grouped by suite.

You can search, filter by status, and sort the list to find what you need, and use **Select all** to pick everything that matches. At least one suite or test is required.

### When to run

Choose how often the schedule repeats:

| Repeats | What it does |
| --- | --- |
| **Once** | Runs a single time at the date and time you pick. The schedule is marked **Completed** afterwards. |
| **Interval** | Runs every **15 minutes**, **30 minutes**, or **hour** — the shortest of these your plan allows. |
| **Weekly** | Runs at a set time on the days you tick (Sun–Sat). |
| **Monthly** | Runs at a set time on a chosen day of the month (1–31). If a month is shorter than that day, it runs on the last day of that month instead. |
| **Custom dates** | Runs on each specific date and time you add to the list. |

Times are entered in your browser's **local timezone**, which TestOwl detects automatically. The schedule keeps that timezone, so a `9:00 AM` schedule stays at 9:00 AM local time throughout the year.

:::callout{title="Times snap to 5-minute steps"}
Times are chosen in 5-minute steps (for example 9:00, 9:05, 9:10), and a one-time or custom date must be in the future.
:::

## Statuses

| Status | Meaning |
| --- | --- |
| **Active** | The schedule is running normally. |
| **Paused** | You paused it, so no new occurrences run until you resume it. |
| **Paused (auto)** | TestOwl paused it because something it depends on changed — see below. Hover the badge to see the reason. |
| **Completed** | A **Once** or **Custom dates** schedule that has no future occurrences left. It cannot be resumed. |

Use the **Pause** / **Resume** buttons on a row (or the bulk buttons in the toolbar) to change a schedule. Deleting a schedule cannot be undone.

## Automatic pausing and resuming

Schedules protect themselves so a broken setup doesn't fail silently.

- **Targets that can no longer run.** If none of a schedule's suites or tests can run any more — each was deleted, archived, or (when the schedule uses a Production environment) set to **Draft** — TestOwl pauses the schedule (**Paused (auto)**) and tells you why. If some targets are still runnable, the schedule keeps running with those.
- **Restored targets.** If you restore a deleted suite or test from the [Recycle Bin](/docs/workspace/recycle-bin), or make it runnable again, the schedule resumes on its own.
- **Quota reached.** If an occurrence can't run because your plan's monthly cloud execution quota is used up, that occurrence is skipped, the schedule is paused, and it resumes automatically once quota is available again (for example after renewal or an upgrade).
- **Read-only projects.** Occurrences are skipped while a project is read-only because its trial ended or a plan is needed. See [Plans & Usage](/docs/team-and-account/plans-and-usage).

## Viewing a schedule's runs

Click the **View runs** (history) icon on a schedule to open its activity drawer. It shows:

- **Targets** — the suites or tests the schedule runs, with a note if any are no longer runnable.
- **History** — past occurrences, with **Scheduled For**, **Status**, **Retries**, **Details**, and links to the runs each occurrence created. History goes back **90 days** and you can filter by date range and outcome.
- **Upcoming** — the next occurrences that are queued.

Each occurrence has one of these outcomes:

| Outcome | Meaning |
| --- | --- |
| **Pending** | Waiting for its scheduled time. |
| **Dispatching** | Being handed to the runner right now. |
| **Dispatched** | The run(s) started. Open them from the **Runs** column, or from [Run History](/docs/running-and-results/run-history). |
| **Failed** | TestOwl could not start the run. It retries up to three times before giving up. |
| **Missed** | The occurrence was more than 30 minutes late (for example after an outage), so it was skipped instead of running at an unexpected time. |
| **Skipped** | The occurrence was skipped instead of running — for example because your plan's execution quota was used up or the project was read-only. |

Runs started by a schedule show a **Scheduled** badge in Run History; click it to jump back to the schedule.

## Email alerts

When something needs attention — a scheduled run failed, was missed, had issues starting part of its targets, or a schedule was paused or resumed — TestOwl emails the project's Owners and Admins.

## Who can manage schedules

Creating, editing, pausing, resuming, and deleting schedules requires the **Admin** or **Owner** role. Editors and Viewers can see the list and each schedule's run history. See [Project Roles](/docs/team-and-account/project-roles).

## Plan limits

| Plan | Schedules | Shortest interval |
| --- | --- | --- |
| Trial | Unlimited | 15 minutes |
| Starter | 5 | 60 minutes |
| Pro | 25 | 30 minutes |
| Scale | Unlimited | 15 minutes |

When you reach your schedule limit, the **New Schedule** button becomes an upgrade button. See [Plans & Usage](/docs/team-and-account/plans-and-usage) for the full plan comparison.

## Best practices

- Schedule a fast **smoke** suite frequently and your full regression suite nightly.
- Point scheduled runs at a stable [Environment](/docs/environments/overview) such as Staging.
- Keep tests you rely on **Active** — a Draft test can't run against a Production environment and an Archived one can't run at all.
- Use a descriptive name so the alert emails are easy to recognise.

## Next steps

::::cardgrid
:::card{title="Triggering a Run" href="/docs/running-and-results/triggering-a-run"}
Start a run manually, on demand.
:::

:::card{title="Run History" href="/docs/running-and-results/run-history"}
See every run, including the ones your schedules started.
:::

:::card{title="Notifications" href="/docs/workspace/notifications"}
Learn how TestOwl alerts you about schedules and plan usage.
:::
::::