---
title: Tests Quickstart
description: Write and run your first Cuitty test suite in five minutes.
section: Tests
order: 1
updatedAt: 2026-05-31
slug: tests/quickstart
---
# Tests Quickstart

Cuitty Tests lets you write declarative HTTP smoke tests in `.ctest` files, run them from the CLI or CI, and review results in Test Studio. This guide takes you from install to a passing suite in under five minutes.

## Install the CLI

```bash
curl -fsSL https://cuitty.com/install.sh | sh
cui --version
```

Or install with npm:

```bash
npm install -g @cuitty/cli
```

## Write your first .ctest file

Create `smoke.ctest` in your project root. Cuitty tests use an HCL-based DSL:

```hcl
suite "api-smoke" {
  description = "Verify core API endpoints return 200"

  test "healthcheck" {
    request {
      method = "GET"
      url    = "${env.BASE_URL}/health"
    }

    assert {
      status = 200
    }
  }

  test "list-projects" {
    request {
      method = "GET"
      url    = "${env.BASE_URL}/api/projects"
      headers = {
        Authorization = "Bearer ${env.CUITTY_API_KEY}"
      }
    }

    assert {
      status  = 200
      json    = "$.data | length > 0"
    }
  }
}
```

## Run the suite

Execute the test file against your running environment:

```bash
cui tests run smoke.ctest --env BASE_URL=http://localhost:7700
```

The CLI prints a pass/fail summary for each test. Use `--verbose` to see full request and response bodies.

## View results in Test Studio

If you have the Cuitty portal running, results are automatically pushed to Test Studio. Open the portal and navigate to **Tests > Runs** to see the timeline, latency breakdown, and assertion details for every request.

## Add tests to CI

Drop a step into your GitHub Actions workflow:

```yaml
- name: Run Cuitty tests
  uses: cuitty/test-action@v1
  with:
    files: "**/*.ctest"
    env: |
      BASE_URL=${{ vars.STAGING_URL }}
      CUITTY_API_KEY=${{ secrets.CUITTY_API_KEY }}
    fail-on: "any"
```

The action uploads results to Test Studio and fails the workflow if any assertion breaks.

## What's next

- [Test DSL reference](/product/tests#dsl) — full syntax for suites, tests, variables, and assertions
- [Test Studio](/product/tests#studio) — dashboard features, diffing, and trend analysis
- [CI integration](/product/tests#ci) — GitHub Actions, GitLab CI, and generic webhook triggers
- [Runner configuration](/product/tests#runner) — parallelism, retries, timeouts, and environment files