Get Help

CAT in Windows Task Scheduler

No CI platform, no SQL Server Agent — just a Windows machine and a time of day. Task Scheduler runs CAT CLI (or the PowerShell module) on a schedule; the part to get right is the account the task runs as, because the license key and the environment variables belong to it.

Before you start

Windows Task Scheduler is a scheduler and CAT recognizes it: a run it starts is an autonomous run, which needs the Enterprise plan and a license key — from CAT 3.0 a task without the key stops before any test runs — see Integrations. Decide which Windows account the task runs as — a service account is the usual choice — because three things are stored per user: the license key (%APPDATA%\CAT\.catconfig), user-level environment variables, and the PowerShell module when installed with -Scope CurrentUser.

Prepare the account

Sign in as that account once (or run the commands under it with runas) and:

  1. Install CAT CLI — winget install DataTools.CATCLI --version 3.0.0 (the version you tested with — pin it), or the installer; it installs per machine. (Or the PowerShell module with -Scope AllUsers.)
  2. Set the key: catcli instance --setLicenseKey "<key>" (or Set-CatInstance -LicenseKey).
  3. Define the environment variables the project file references — DWH_CONNECTION_STRING and friends — at machine level (seen by every account, new sessions) or at user level for that account. See Use environment variables.
  4. Run the project by hand from that account once: catcli run -p "D:\CAT\DWH\DwhTests.cat.yaml". If it works here, it works in the task.

Create the task

Task Scheduler → Create Task…:

Tab Setting
General When running the task, use the following user account: the prepared account. Run whether user is logged on or not.
Triggers the schedule — daily at 06:00, after every load, whatever the tests are for
Actions Start a program — Program: catcli (or its full path, C:\Program Files\CAT CLI\catcli.exe); Arguments: run -p "D:\CAT\DWH\DwhTests.cat.yaml" -l Error; Start in: the project’s folder, so relative paths in the project file resolve
Settings Stop the task if it runs longer than … — a ceiling that suits your run

With the PowerShell module the action is pwsh with arguments -NoProfile -File "D:\CAT\Run-DwhTests.ps1" and a script that imports the module and calls Invoke-CatProject.

Results

The task has no screen to read; give the project outputs — an Excel file with {timestamp} in the name for people, a database table or JSON for a process that reacts. -l Error writes the failed tests’ details to CAT’s log (Documents\CAT\Logs\ of the task’s account). With CAT CLI, Task Scheduler’s Last Run Result is CAT’s exit code: 0 when every test passed, 10 on a failed test, also non-zero when the project could not be opened or the sign-in and plan check refused it; add --exitCode run to the task’s arguments for a task that must only alert when the run itself broke, not on a failed test — see Results and exit codes. With the PowerShell wrapper script, Last Run Result is pwsh’s own exit code, which the script controls.

← CAT in SQL Server Agent
CAT in cron →