> For the complete documentation index, see [llms.txt](https://sevenval.gitbook.io/flat/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sevenval.gitbook.io/flat/reference/testing.md).

# Testing

FLAT provides a built-in test framework. It is especially useful to unit-test [templates](/flat/reference/templating.md), error handling and upstream requests.

## Syntax

FLAT tests are defined as [flow](/flat/reference/flow.md) files with the root node `flat-test`. There are a couple of specialized [test actions](/flat/reference/actions.md#test-actions) that accompany the test flow. The invocation of at least one [`assert` action](/flat/reference/actions/assert.md) is mandatory.

```markup
<flat-test>
  <!-- flow code -->

  <assert>
  [
    [ … ]
  ]
  </assert>
</flat-test>
```

## Directories

Test files can be stored anywhere inside the FLAT app directory. We recommend creating a `tests/` folder next to `swagger.yaml`.

## Command

FLAT tests are started with the [`flat` cli](/flat/reference/flat-cli.md) command `test`:

```bash
$ flat test tests/test-foo.xml tests/test-bar.xml
```

The test result is printed in [TAP](https://testanything.org) format:

```
1..2
ok 1 tests/test-foo.xml: 17 assertions
ok 2 tests/test-bar.xml: 4 assertions
passed: 2, failed: 0
```

If *all* tests pass, the exit code is `0`. If *any* test fails, the code is non-zero (`1`). Therefore, in deployment scripts or `Makefile` recipes (both of which are usually executed as `set -e`) you can rely on the exit code to fail the process.

## See also

* [Testing Templates](/flat/cookbook/test-templates.md) (cookbook)
* [Testing API Requests](/flat/cookbook/test-api-request.md) (cookbook)
* [Testing Upstream Requests](/flat/cookbook/test-backend.md) (cookbook)
* [Test Actions](/flat/reference/actions.md#test-actions) (reference)
  * [`assert`](/flat/reference/actions/assert.md) (reference)
  * [`backend-flow`](/flat/reference/actions/backend-flow.md) (reference)
  * [`set-env`](/flat/reference/actions/set-env.md) (reference)
  * [`test-request`](/flat/reference/actions/test-request.md) (reference)