Skip to main content

Tutorial: your first test run

In this tutorial you connect the CLI to Teststream, write a small test, check it, put it on a branch and run it. It takes about 15 minutes.

You need:

  • Node.js 22 or newer.
  • A Teststream account (the hosted Teststream, or a self-hosted server you can reach), and a project in it (you need its slug, for example RWA).
  • A checkout of your app's repository, on a git branch other than main.
  • For the payment example below: a disposable demo application with the described screens, a Demo environment, and a configured user login role with a test account and contact. Do not run this example against real payments.

1. Get the CLI​

Install the CLI from npm:

npm install -g teststream
teststream --version

teststream help should list the commands. To run it with npx instead, see Set up the CLI.

2. Connect it to your project​

Create an API key under Organization > Keys > Teststream API keys, and securely supply it as TESTSTREAM_API_KEY as described in CLI setup. Set the project:

export TESTSTREAM_PROJECT="RWA"

The CLI uses the hosted Teststream by default. On a self-hosted server, also set TESTSTREAM_URL to its API, for example https://teststream.example.com/api.

Check the connection by listing the project's tests:

teststream tests list

You should see one line per test: key, name and folder. An empty list is fine for a new project.

3. Write a test​

Create pay-contact.yaml:

name: Pay a contact a small amount
role: user
start: /transaction/new
folder: Transactions
steps:
  - when: I select the first contact
  - and: I enter the amount "5"
  - and: I click "Pay"
  - then: the transaction appears in the list with amount "$5.00"

Each step is one action or one check, written in the words the app shows. role: user starts the test already logged in, so there are no login steps.

4. Validate it​

teststream tests validate pay-contact.yaml

You should see pay-contact.yaml: valid. If a field is wrong, the CLI prints the line number and the problem. Fix it and run the command again. Warnings (for example about logging in) are advice and do not fail the check.

5. Put it on a branch​

Propose the test on a named feature branch:

teststream tests push pay-contact.yaml --branch feature/pay-contact

The output identifies the proposed test key and branch. A teammate reviews the proposal in Branches. It reaches main only after acceptance and the Teststream change set's merge.

note

On main, master, trunk or develop the CLI refuses to push and asks for --branch <name> or --main. See How Teststream runs tests.

6. Run it​

teststream run --tests "RWA-1" --branch feature/pay-contact --env Demo --wait

Replace RWA-1 with the key printed by tests push. The CLI waits and prints counts, estimated cost and the actual run link. Illustrative output:

Run 14: completed · 1/1 passed · est. $0.12
https://app.teststream.ai/runs/…

Open the link to inspect the step evidence. Later runs can replay usable recordings without model calls, but missing/changed recordings or recovery may use AI again. Do not repeat a payment test without resetting its demo data and checking the consequences.

What you learned​

You connected the CLI, wrote and validated a test, proposed it on a branch and ran it. Next: