Scheduling

Run flows on a cron schedule to continuously validate your services, detect regressions early, and monitor production systems around the clock.

TestMesh includes a built-in scheduler that executes flows automatically on a cron schedule. Scheduled runs are stored with full execution history so you can track trends, spot regressions, and get notified on failures.

How Scheduling Works

The scheduler is powered by Redis Streams for reliable job queuing. When a scheduled time arrives:

The scheduler enqueues a job into Redis Streams.

A worker picks up the job and executes the flow.

Results are stored in the executions table with the schedule ID attached.

Notifications are sent if the execution fails (configured per schedule).

Creating Schedules

Via the Dashboard

Navigate to Schedules in the dashboard sidebar and click New Schedule. Configure:

Flow — Select the flow to run
Cron expression — When to run it
Environment — Which environment variables to use
Notifications — Slack, email, or webhook on failure

Via the API

curl -X POST http://localhost:5016/api/v1/workspaces/{workspace_id}/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly Health Check",
    "flow_id": "flow-uuid-here",
    "cron_expr": "0 * * * *",
    "environment": {},
    "notify_on_failure": false
  }'

Cron Expression Format

TestMesh uses standard 5-field cron syntax:

┌───── minute (0–59)
│ ┌───── hour (0–23)
│ │ ┌───── day of month (1–31)
│ │ │ ┌───── month (1–12)
│ │ │ │ ┌───── day of week (0–6, Sunday=0)
│ │ │ │ │
* * * * *

Common Schedules

Expression	Meaning
`* * * * *`	Every minute
`0 * * * *`	Every hour
`0 9 * * 1-5`	Weekdays at 9:00 AM
`0 /4 * *`	Every 4 hours
`30 8 * * *`	Daily at 8:30 AM
`0 0 * * 0`	Weekly on Sunday at midnight
`0 0 1 * *`	Monthly on the 1st at midnight

Use crontab.guru to validate and preview cron expressions before saving a schedule.

Example: Production Health Monitoring

Schedule a health-check flow to run every 5 minutes and alert on failure:

health-check.yaml

flow:
  name: "Production Health Check"
  description: "Verify all services are responding correctly"

  steps:
    - id: check_user_service
      action: http_request
      config:
        method: GET
        url: "${USER_SERVICE_URL}/health"
        timeout: 5s
      assert:
        - status == 200
        - response.body.status == "ok"

    - id: check_order_service
      action: http_request
      config:
        method: GET
        url: "${ORDER_SERVICE_URL}/health"
        timeout: 5s
      assert:
        - status == 200

    - id: check_database
      action: database_query
      config:
        query: "SELECT 1"
      assert:
        - result.count == 1

    - id: check_kafka
      action: kafka_produce
      config:
        brokers: ["${KAFKA_BROKERS}"]
        topic: "health.checks"
        value:
          timestamp: "${TIMESTAMP}"
          source: "testmesh"

Configure the schedule:

{
  "name": "Production Health Check (every 5 min)",
  "flow_id": "health-check-flow-id",
  "cron_expr": "*/5 * * * *",
  "timezone": "UTC",
  "notify_on_failure": true,
  "notify_emails": ["oncall@example.com"]
}

Execution History

Every scheduled run creates an execution record visible in the dashboard. The Schedules view shows:

Next scheduled run time
Last run status (pass / fail)
Pass rate over the last 30 days
Average duration trend

Drill into any scheduled execution to see full step-level detail, logs, and request/response inspection — identical to manually triggered executions.

Enable and Disable Schedules

Schedules can be toggled without deleting them — useful when deploying a change and temporarily pausing a schedule:

# Pause a schedule
curl -X POST http://localhost:5016/api/v1/workspaces/{workspace_id}/schedules/{schedule_id}/pause

# Resume it
curl -X POST http://localhost:5016/api/v1/workspaces/{workspace_id}/schedules/{schedule_id}/resume

Schedules have three statuses: active, paused, and disabled. Pausing sets it to paused; deleting is the only way to fully remove it.

In the dashboard, use the toggle switch on each schedule row.

Time Zone Support

Schedules run in UTC by default. Specify a time zone to schedule relative to local business hours:

{
  "name": "Business Hours Report",
  "cron_expr": "0 9 * * 1-5",
  "timezone": "America/New_York"
}

All supported IANA time zone names are accepted.

Notifications on Failure

Configure failure notifications per schedule using notify_on_failure and notify_emails:

{
  "name": "Nightly Regression",
  "flow_id": "flow-uuid",
  "cron_expr": "0 2 * * *",
  "notify_on_failure": true,
  "notify_emails": ["team@example.com", "oncall@example.com"]
}

When a scheduled run fails, TestMesh sends an email to all addresses in notify_emails with the flow name, which step failed, and a link to the execution detail page.

Using Environments with Schedules

Attach environment variables to a schedule so the same flow can run with different configuration in different contexts:

{
  "name": "Staging Health Check",
  "flow_id": "health-check-id",
  "cron_expr": "*/10 * * * *",
  "environment": {
    "USER_SERVICE_URL": "http://user-service.staging",
    "ORDER_SERVICE_URL": "http://order-service.staging"
  }
}

Create a separate schedule record for each target environment — one for staging, one for production.

See the Environments documentation for how to define reusable environment variable sets.

Scheduling

On this page