Step-by-step runbooks for the things no suite can prove — real COM, real Windows, real eyes.

Some things genuinely can't be automated cheaply — or at all. Real Task Scheduler COM, the Docker stack booting from a clean checkout, whether a PowerShell window flashes, whether the dashboard looks right. This folder is where those live as runbooks you can follow without thinking: exact commands, exact expected output.

These runbooks exist to close the ⬜ rows in functional, integration, and regression. Each one names the IDs it covers.

Every runbook assumes these three things. Do them first.

pwsh .\scripts\cronsole.ps1 up
pwsh .\scripts\cronsole.ps1 status

status should show every service up: Postgres, Redis, backend (:3000), frontend (:7373), and the agent.

Invoke-RestMethod http://localhost:3000/api/health

/api/health is unauthenticated — it's a liveness probe, so a 200 here only proves the process is answering.

If the port listens but nothing answers (HTTP 000), the app crashed behind Docker's port proxy — see troubleshooting #3.

Every /api/tasks/* and /api/templates/* route is auth-gated. Grab the token from frontend/.env.local (VITE_DEV_TOKEN), or mint one signed with the backend's JWT_SECRET:

cd backend
node -r dotenv/config -e "console.log(require('jsonwebtoken').sign({id:'cli_user_placeholder',email:'mike@example.com'}, process.env.JWT_SECRET, {expiresIn:'3650d'}))"

Then keep it in a variable for the session:

$env:TH_TOKEN = '<paste token>'
$H = @{ Authorization = "Bearer $env:TH_TOKEN" }

Verify it works:

Invoke-RestMethod http://localhost:3000/api/tasks -Headers $H

Expect: a JSON array of tasks (possibly empty). A 403 Invalid or expired token means your token was signed with a different secret than the running backend is using — the classic Docker-defaults mismatch, see troubleshooting #2.

Handy while working through the runbooks. Everything except /api/health and /api/auth/* requires the Authorization: Bearer header.

The two easiest to get wrong (platform is required on both, and the name field is name — not taskName):

// POST /api/templates/:id/apply
{
  "platform": "WINDOWS_TASK_SCHEDULER",  // required; also arms the duplicate-name guard
  "name": "my-task",                     // optional — defaults to the template's name
  "schedule": "0 3 * * *",               // 5-field cron, UTC (or "scheduleExpression")
  "parameters": { }                      // raw values; the SERVER substitutes {{placeholders}}
  // "command" also exists but is DEPRECATED (pre-substituted, legacy clients only)
}

// POST /api/templates/:id/preview  → { score, warnings[], trigger }
{
  "platform": "WINDOWS_TASK_SCHEDULER",
  "schedule": "0 3 * * *"
}

platform accepts any PlatformType: WINDOWS_TASK_SCHEDULER, TASKHUB_NATIVE, CLAUDE_CODE, MACOS_LAUNCHD, CHATGPT, JULES, OPEN_CLAW, HERMES — but only Windows and Cronsole-native have real compilers today.

Every runbook uses the same shape, so you can follow one half-asleep:

• Numbered steps — one action each.
• Expect: what you should see. If you see something else, that's a finding.
• Cleanup — every runbook that creates state removes it. Never leave test tasks in Task Scheduler.
• Covers: the test IDs from the other layers, so coverage stays traceable.

Add one when you hit something that can't be automated, or that burned you once and will again. Keep it copy-pasteable — a runbook you have to interpret is a runbook nobody runs.

1. Write it as numbered steps with an Expect: after each.
2. Cite the test IDs it covers, and flip those rows in the layer README to point here.
3. Add a row to the runbook table above.
4. If a step is really an automatable check, automate it instead and delete the step. This folder should shrink over time, not grow.

(back to top)

← Testing Home · Functional · Integration · Regression · UAT