---
title: "Run tests in parallel"
description: "When to raise the degree of parallelism, how far, and where the Threads setting goes"
url: "https://docs.justcat.it/how-to-guides/organize-and-run-tests/run-tests-in-parallel/"
---
# Run tests in parallel


## Where the setting goes

`Threads` is a **root setting** — a key at the very beginning of a line, at the same level as `Data sources:` and `Tests:`, not inside any of them. In context:

```yaml
Threads: 3

Data sources:
- Name: DWH
  Provider: SqlServer@2
  Connection string: "%DWH_CONNECTION_STRING%"

Tests:
- Name: Currency dimension is loaded
  Data source: DWH
  Query: SELECT * FROM Dimension.Currency
  Expectation: set is not empty
```

It accepts a positive whole number (or an environment variable that holds one, `"%CAT_THREADS%"`), defaults to `1`, and CAT refuses `0`, negatives and non-numbers before any test starts — see [Root settings](https://docs.justcat.it/reference/project-file/root-settings/ "Root settings"). In CAT Studio the same value is on the Project page, under the project's settings. Every tool honours it; there is no per-run override.

## When it helps

When a run takes long and the time is spent waiting on the databases — many tests, each a query that runs for seconds. Three threads then evaluate three tests at once, and the run shortens accordingly. It does not help a run dominated by one slow test, and it does not make a single query faster.

> **🙀:** **Before you raise the number.** Every thread is another query running against your servers at the same time. That load lands on the same databases other people and applications use; deciding how much of it is acceptable is the tester's responsibility, not CAT's.



## How far

* If you have no reason to use parallelism, leave the key out.
* Raise it in steps — two, then three — and watch the run time; past some point the database, not CAT, is the limit and more threads only add load.
* Tell your database administrators before you do, and watch the load with them.
* `Excel@2` and `Csv@2` load the whole worksheet or file into memory per thread; with hundreds of thousands of rows keep such tests single-threaded, in a project file of their own if need be.
* At `Debug` logging the log records which thread ran which test and when — useful when something looks off, not for everyday runs.

## Related

* [Root settings](https://docs.justcat.it/reference/project-file/root-settings/ "Root settings") — `Threads` in the reference.
* [Complete example](https://docs.justcat.it/reference/project-file/complete-example/ "Complete example") — a whole project file, `Threads` in place.