Scheduled Runs

Automate test execution on a recurring basis using cron expressions. Configure schedules for entire projects or individual suites, and manage data retention to keep your disk usage under control.

Overview

Scheduled runs let you execute your tests automatically on a recurring basis without manual intervention. Each schedule is tied to a project and optionally to a specific test suite. When a schedule fires, it runs all project tests (or the suite's tests) with a concurrency of 2, records the results, and updates the schedule's status tracking fields.

Schedules are managed through the REST API and persisted in the SQLite database. On server startup, all enabled schedules are reloaded via loadAllSchedules(), ensuring that your automation survives server restarts.

Creating a Schedule

To create a schedule, send a POST request to the schedules endpoint with the following fields:

{
  "projectId": "proj_abc123",
  "name": "Nightly Regression Suite",
  "cronExpression": "0 0 * * *",
  "suiteId": "suite_xyz789",
  "enabled": true
}

The server validates the cron expression using the node-cron library. If the expression is invalid, a 400 error is returned. If the schedule is enabled, it is immediately activated via scheduleJob().

Cron Expression Format

Cron expressions follow the standard five-field format:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-7, where 0 and 7 are Sunday)
│ │ │ │ │
* * * * *

Common Presets

Here are some commonly used cron expressions:

Schedule Behavior

When a schedule fires:

• If a suiteId is set, only the tests in that suite are executed.
• If no suiteId is set, all tests in the project are executed.
• Tests run with a concurrency of 2, meaning up to 2 tests execute in parallel.
• Each test execution creates a run record, exactly as if you had manually triggered the run.
• Results contribute to the analytics dashboard (pass rate, trends, flaky detection).

Schedule Status Tracking

Each schedule record tracks its execution history through three status fields:

These fields allow you to monitor schedule health at a glance and detect any schedules that may be consistently failing.

Enable / Disable Toggle

Schedules can be enabled or disabled at any time by updating the enabled field. When a schedule is disabled, its cron job is unregistered via unscheduleJob() and it will not fire until re-enabled.

{
  "enabled": false
}

When re-enabled, the schedule is immediately re-registered with the cron scheduler. You can also update the name, cronExpression, and suiteId in the same request.

Managing Schedules

The full set of schedule management endpoints:

Data Cleanup & Retention

As tests run automatically on a recurring basis, run records, screenshots, videos, and diff images accumulate over time. QA Studio includes an automatic cleanup system to manage disk usage.

Retention Configuration

The retention period is controlled by the RETENTION_DAYS environment variable:

Automatic Cleanup

The cleanup system runs automatically in two ways:

• On server startup — A deferred cleanup runs 5 seconds after the server starts, removing any data older than the retention period.
• Daily at 3:00 AM — A cron job (0 3 * * *) runs the cleanup every day via startCleanupSchedule().

The cleanup process removes:

• Old run records — Deleted from the runs table.
• Old suite run records — Deleted from the suite_runs table.
• Screenshot files — Deleted from disk for expired runs.
• Video files — Deleted from disk for expired runs.
• Diff image files — Actual and diff images for expired runs are removed. Baseline images referenced by diffs are preserved.

Manual Cleanup

You can trigger a cleanup on demand at any time using the admin endpoint:

POST /api/admin/cleanup

This runs the same cleanup logic as the automatic schedule, using the current RETENTION_DAYS value. The response confirms success:

{
  "success": true
}

Example Workflow

A typical scheduling workflow looks like this: