---
title: "Introduction"
description: "What the .cat.yaml file is, how tools find it, and what it must contain"
url: "https://docs.justcat.it/reference/project-file/introduction/"
---
# Introduction


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:

```yaml
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](https://docs.justcat.it/reference/project-file/complete-example/ "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.

> **🐱:** **Use the `.cat.yaml` extension.** A file with any other extension cannot be found by folder resolution, and no CAT tool creates or offers one.



## 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.

| Key | Contains | Reference |
|---|---|---|
| `Data sources` | Data source definitions written in this file | [Data sources](https://docs.justcat.it/reference/data-sources/properties/ "Data source properties") |
| `Queries` | Query definitions written in this file | [Queries](https://docs.justcat.it/reference/queries/properties/ "Query properties") |
| `Tests` | Test definitions written in this file | [Tests](https://docs.justcat.it/reference/tests/properties/ "Test properties") |
| `Get list of data sources from` | External lists of data source definitions | [Lists](https://docs.justcat.it/reference/project-file/lists/ "Lists") |
| `Get list of queries from` | External lists of query definitions | [Lists](https://docs.justcat.it/reference/project-file/lists/ "Lists") |
| `Get list of tests from` | External lists of test definitions | [Lists](https://docs.justcat.it/reference/project-file/lists/ "Lists") |
| `Output` | Where and in what format results are written | [Output settings](https://docs.justcat.it/reference/outputs/settings/ "Output settings") |
| `Threads` | Degree of parallelism for test execution | [Root settings](https://docs.justcat.it/reference/project-file/root-settings/ "Root settings") |

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](https://docs.justcat.it/reference/project-file/lists/ "Lists — implicit and explicit").

`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](https://docs.justcat.it/reference/project-file/naming-conventions/ "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](https://docs.justcat.it/reference/project-file/environment-variables/ "Environment variables").

## Related

* [Complete example](https://docs.justcat.it/reference/project-file/complete-example/ "Complete example") — one file that exercises most of what the project file accepts.
* [Create a project file](https://docs.justcat.it/how-to-guides/organize-and-run-tests/how-to-create-project-file/ "Create a project file") — creating one from a template.
* Project files use YAML syntax. For an introduction to YAML itself: <a href="https://www.cloudbees.com/blog/yaml-tutorial-everything-you-need-get-started" target="_blank">YAML tutorial</a>.