Introduction

The project file is what every CAT tool opens: it says what to connect to, what to test, and where the results go.

A CAT project file is a plain text file in YAML format. It is the single input every CAT tool reads: the tool opens a project file, resolves the definitions it points to, runs the tests and writes the outputs.

A minimal project file — one data source, one test, one output:

Data sources:
- Name: FlightsSystem
  Provider: SqlServer@2
  Connection string: data source=localhost;initial catalog=DWH;integrated security=true

Tests:
- Name: Departures are loaded
  Data source: FlightsSystem
  Query: SELECT * FROM FACT.DEPARTURES
  Expectation: set is not empty

Output:
- File: TestResults.xlsx
  Format: xlsx

Everything the file accepts is shown in the Complete example.

File name and resolution #

A project file is named <name>.cat.yaml. You hand it to a tool in one of three ways:

• a path to the file — C:\Tests\Flights.cat.yaml — the tool opens that file;
• a path to a folder — C:\Tests — the tool looks for a *.cat.yaml file in that folder and opens it;
• nothing — the tool does the same with the working directory.

The folder forms work only when the folder holds exactly one *.cat.yaml file. Zero or several is an error — pass the path to the file you mean instead. CAT Studio only accepts path to a file.

Both absolute and relative paths are supported.

What a project must contain #

Every project needs data sources and tests. Each of them can be written in the file, pointed to elsewhere, or both:

• data sources — under Data sources:, or under Get list of data sources from:, or both;
• tests — under Tests:, or under Get list of tests from:, or both.

CAT refuses to run a project that has neither key of a pair and says so (“There are no tests defined. Either use ‘Tests:’ or ‘Get List of Tests from:’”). Everything else — queries, outputs, Threads — is optional.

Top-level keys #

Every key below sits at the root of the document — no indentation before it.

The keys come in two flavours. Data sources, Queries and Tests hold definitions written in this file. Get list of … from keys point to definitions kept elsewhere — other YAML files, workbooks, database tables, stored procedures, anything a provider can return rows from. A file can use either flavour alone or both together; see Lists.

Output and Outputs address the same key. Queries was previously called Named sets, and that name is still accepted.

Keys and properties are matched by synonym and are not case sensitive: Data sources, Data_Sources and DataSources all address the same key. See Naming conventions.

%NAME% anywhere in the file is replaced with the value of the environment variable NAME, when such a variable exists. See Environment variables.

Related #

• Complete example — one file that exercises most of what the project file accepts.
• Create a project file — creating one from a template.
• Project files use YAML syntax. For an introduction to YAML itself: YAML tutorial.