# Testfile

> A declarative YAML format for running a project's tests: one file describes
> what to run, what it needs (services, ports, containers) and how to select
> subsets of it, so the same suite runs on a laptop and in any CI system.

The format is specified independently of its implementation. This site
documents the reference implementation (the `testfile` command line) and
the normative specification it follows.

## Documentation

- [Get started](https://testfile.dev/start): a wizard: pick a language and version, local or container, and a PostgreSQL version - or all of them, which fans the suite out over every one - and the page writes the starter Testfile for exactly that
- [What is a Testfile?](https://testfile.dev/docs/index): A declarative YAML format that describes how your project runs its tests.
- [Getting started](https://testfile.dev/docs/getting-started): Write your first Testfile and run it.
- [CLI & TUI](https://testfile.dev/docs/cli): The testfile command line runner and its interactive terminal UI.
- [Screenshots](https://testfile.dev/docs/screenshots): What the web viewer and the terminal UI look like, view by view.
- [CLI reference](https://testfile.dev/docs/cli-reference): Every command and argument of the testfile command line.
- [Writing tests](https://testfile.dev/docs/writing-tests): Commands, scripts, sequences, parallel groups and failure handling.
- [Matrix builds](https://testfile.dev/docs/matrix): Run one test across many combinations of versions and variants.
- [Services](https://testfile.dev/docs/services): Start the app under test, databases and other dependencies — and stop them gracefully.
- [Environment & ports](https://testfile.dev/docs/env-and-ports): Environment variables, random ports and template expressions.
- [A complete Testfile](https://testfile.dev/docs/complete-example): One file using nearly every feature at once, annotated — a map of the format rather than a template to copy.
- [GitHub Action](https://testfile.dev/docs/github-action): Run your Testfile in GitHub Actions with one step.
- [GitLab CI](https://testfile.dev/docs/gitlab-ci): Run your Testfile in GitLab CI with one include.
- [Tekton](https://testfile.dev/docs/tekton): Run your Testfile as a Tekton Task — with the services as pods on the same cluster.
- [Other CI systems](https://testfile.dev/docs/ci-systems): Run a Testfile on GitLab CI, Jenkins, CircleCI or Buildkite — and bring those runs home.
- [Exporting pipelines](https://testfile.dev/docs/export): Generate a native GitHub Actions, GitLab CI, Tekton or bash pipeline that runs the suite without the testfile runner.
- [Viewer & sync](https://testfile.dev/docs/review-results): Browse recorded runs in the TUI or the web viewer, and pull CI runs into the local history with testfile github sync.

## Specification

- [Testfile specification (v0)](https://testfile.dev/spec/testfile): The normative specification of the Testfile format: how a project describes its tests.
- [Test result format (v0)](https://testfile.dev/spec/test-result): The normative specification of a recorded test run: the run folder, run.yaml and the logs next to it.
- [Versioning and compatibility policy](https://testfile.dev/spec/versioning): How the Testfile format evolves and what runners and users can rely on.

## Guides

- [pytest + PostgreSQL](https://testfile.dev/guides/pytest-postgres): Unit tests without a database, integration tests against a real PostgreSQL container — migrations applied in a setup hook, on a random port.
- [Playwright + web app](https://testfile.dev/guides/playwright-web): Build the app, start API and frontend as services, run the browser tests against them — traces and screenshots are kept with the run.
- [Go + containers](https://testfile.dev/guides/go-containers): Testcontainers-style dependencies — Redis and Kafka — declared in the Testfile instead of started from test code, so `go test` stays plain.
- [Matrix across versions](https://testfile.dev/guides/node-matrix): One test definition, five runs: three Node versions against two PostgreSQL versions, with one unsupported combination excluded.
- [Monorepo](https://testfile.dev/guides/monorepo): Each package owns its Testfile; the root file only wires them together with glob includes, so teams stay independent.
- [Guided tour: three platforms](https://testfile.dev/guides/three-platforms): Run one Testfile on Linux, macOS and Windows in GitHub Actions and merge the three runs into a single result.

## Blog

- [Blog](https://testfile.dev/blog): news about the Testfile format and its tooling, newest first
- [A new home for testfile.dev](https://testfile.dev/blog/a-new-home-for-testfile): A refreshed website with a new look, a guides section for complete working Testfiles, and this blog.

## Optional

- [Everything, in one file](https://testfile.dev/llms-full.txt): the full text of every page above, for when the whole documentation should be read at once
- [Source repository](https://github.com/testfile-dev/testfile): the runner, the viewer, the JSON schemas and the conformance suite