Introduction

The conventions shared by every cmdlet of the CAT PowerShell module. Read this page once; the cmdlet pages assume it.

The CAT PowerShell module is the PowerShell face of CAT: 19 cmdlets that open a project file (.cat.yaml), run its tests, hand the results back as objects, and manage the installation. It works with the same project file and runs tests with the same engine as CAT Studio, CAT CLI and the Python module — which tool you use is a matter of environment and taste, not of capability. It requires PowerShell 7.4 or later and runs on Windows and on the Linux distributions where PowerShell 7 is supported. For a hands-on first contact, follow the Get started with the PowerShell module tutorial; this section is the reference.

Install and import #

Install-Module CAT -AcceptLicense -AllowClobber   # once, from the PowerShell Gallery
Import-Module CAT                                  # in every session, before the first cmdlet

Import-Module CAT is not optional. PowerShell’s automatic module loading finds a cmdlet by name in the installed manifests, and the CAT manifest lists the names without the Cat prefix that the cmdlets actually carry — so Get-CatInstance is not found until the module is imported. Importing prints a banner with the documentation and feedback links and the module version; nothing else happens at import (no sign-in, no network). Installation options, pinning a version, upgrade and uninstall are on Installation.

Cmdlets #

Every cmdlet is <Verb>-Cat<Noun>; there are no aliases. By task:

Get-Command -Module CAT lists them; Get-Help <cmdlet> shows the syntax (the module ships no help texts beyond the syntax, so the pages here are the help). No cmdlet supports -WhatIf/-Confirm or pipeline input; the common parameters (-Verbose, -ErrorAction, -WarningAction, …) apply to all.

The session model #

The module keeps one session and at most one open project per PowerShell session, in private module state you never touch directly.

• Open-CatProject (and Invoke-CatProject, which opens internally) creates the session, signs in, opens the project and remembers it. Opening another project replaces the first; nothing has to be closed in between.
• Every cmdlet that works with “the project” — Get-Cat*, Show-CatProject, Invoke-CatTest, Invoke-CatCommand — uses that one open project and fails with There is no CAT project open. Use Open-CatProject to open it. (or There is no CAT session active…) when there is none.
• Invoke-CatProject is the one-liner: open → show → run → show summary. After it, the project stays open and Get-CatTestResultSummary / Get-CatTestResult still read its results.
• Close-CatProject forgets the project and ends the session. It is never required — ending the PowerShell session does the same — but it releases data-source connections.
• New-CatProject and Get-CatProjectTemplate need no open project; they sign in on their own (and reuse the session if one exists). Get-CatInstance and Set-CatInstance neither open nor sign in.

Paths #

-Path on Open-CatProject, Invoke-CatProject and New-CatProject accepts a path to a .cat.yaml file or to a directory; a relative path is resolved against PowerShell’s current location (Get-Location), and an empty or omitted -Path means the current location. A directory must contain exactly one *.cat.yaml file — none or more than one is an error naming the files found. A path that does not exist is refused before anything else happens.

Relative paths inside the project file (test lists, outputs, CSV files, …) are resolved against the project file’s folder.

Logging #

-LoggingLevel on the cmdlets that create the session sets how much CAT logs: None, Fatal, Error, Warning, Information, Debug, Verbose. The level lives with the session, so it is fixed by the cmdlet that created it and inherited by everything that follows until the next Open-CatProject / Invoke-CatProject.

With any level other than None, log lines go to the console and to the log file; the file rolls hourly (cat-log<yyyyMMddHH>.log). -LoggingPath redirects the file. Information shows what CAT does step by step and prints one line per test as it finishes (✅ Passed [Suite].[0].[Name], ❌ Failed …, ❓ Inconclusive …, 🔥 Error …); with None, Fatal, Error or Warning the per-test lines are not printed.

On Linux, Documents resolves to nothing, so the non-project log file lands in ./CAT/Logs/ under the current directory.

Objects on the pipeline, text on the host #

Get-* cmdlets, Open-CatProject, Invoke-CatTest and Invoke-CatCommand write objects to the pipeline (the cmdlet pages list their properties). Show-* cmdlets, Invoke-CatProject, New-CatProject, Close-CatProject and Set-CatInstance write nothing to the pipeline — what you see is host text (coloured, not capturable).

One PowerShell detail matters: the Get-* cmdlets that return several items write the whole list as one object. Get-CatTest | Where-Object … therefore sees a single list, not its items. Assign first, or wrap in parentheses:

$tests = Get-CatTest
$tests | Where-Object Suite -eq 'Departures'
(Get-CatTest) | Measure-Object
(Get-CatTest).Count

Errors #

A refusal from the sign-in and plan check, a plan limit, a bad parameter value or a missing project is a terminating error of the cmdlet: the cmdlet stops, $? is $false, the error is in $Error[0], try/catch catches it, and -ErrorAction SilentlyContinue does not hide it. The next statement of the script still runs unless $ErrorActionPreference = 'Stop' is set or the call is in try. No cmdlet sets $LASTEXITCODE.

Scripts can branch on the stable FullyQualifiedErrorId:

The full id is <prefix>,<cmdlet class>, for example CatPortal.TokenMissing,JC.Cat.Clients.PowerShell.CatModule.OpenProjectCommand. A project that fails to open for any other reason (a YAML error, an unreachable data source list, …) is a non-terminating error from Open-CatProject/Invoke-CatProject — the message is printed and no project is open afterwards.

Failed tests are not errors. Invoke-CatProject and Invoke-CatTest complete normally whatever the results. A script that must fail on failed tests reads the summary:

Invoke-CatProject -Path "D:\Testing\DwhTests.cat.yaml"
$summary = Get-CatTestResultSummary
if ($summary.FailedCount -gt 0 -or $summary.ErrorCount -gt 0) { exit 1 }

Sign-in, plans and the license key #

The command-line tools are available in the Team and Enterprise plans; Starter and Professional cover CAT Studio only — the module refuses to work under them (CatPortal.PlanNotAllowed). See Compare plans.

Team signs in to CAT Portal with a personal access token: create one under Developer → Personal access tokens and put it into the CAT_PORTAL_TOKEN environment variable ($env:CAT_PORTAL_TOKEN = '…' for the session, setx on Windows or your profile for good). Every Open-CatProject / Invoke-CatProject signs in afresh; the other project cmdlets reuse that session. The Team plan is for interactive use only: when CAT detects that it was started by a CI/CD platform (GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, TeamCity and others, through their environment variables) or by a scheduler (Windows Task Scheduler, SQL Server Agent, cron — through the parent process; on Linux also a container runtime), it refuses with CatPortal.InteractiveUsageRequired. Nothing detected means allowed.

Once signed in, CAT caches the authorisation and keeps working without the portal for a limited time; during that time the cmdlet writes the warning Working offline; authorised until <date>. Reconnect before then. (-WarningAction SilentlyContinue hides it). When the portal is unreachable and no usable cache exists, it refuses with CatPortal.OfflineExpired.

Enterprise needs no sign-in and no network at all: set the license key once with Set-CatInstance -LicenseKey and every cmdlet is unlocked, also behind a firewall; with a valid key in place CAT_PORTAL_TOKEN is not read. The key is shared with the other CAT tools on the machine. See Get CAT license and Apply a license key.

The check runs before any work, so a refused cmdlet does nothing — no project is opened, no test runs, no output is written. Get-CatInstance and Set-CatInstance skip it: you can always inspect the installation or set a key on a machine that has no portal access.

Environment variables #

Project files can reference environment variables of their own (connection strings, paths, passwords) — see Environment variables and Use environment variables.

Files the module touches #

Platforms #

One package serves Windows (x64) and Linux. Windows PowerShell 5.1 is not supported — the module needs PowerShell 7.4+. On Linux everything above applies with the Linux paths; the providers built on Windows components — Dax@1, Dax@2, PowerBI@1, PowerBI@2, CsvOleDB@1, ExcelOleDB@1 — are Windows-only, and file names are case-sensitive (a *.cat.yaml project file must be spelled with that case). See CAT on Linux.

Related #

• Installation — Gallery, scopes, pinning, upgrade, uninstall.
• Get started with the PowerShell module — the tutorial.
• Run your tests · Integrations — pipelines that call the module.
• Project file — what the cmdlets operate on.