Docs/Getting Started

CLI Quickstart

Install the CLI, generate your first test, and run it locally.

The Assrt CLI runs on your machine and drives a real browser. This quickstart walks through installing it, authoring a first test from a plain-English description, and running it locally.

1. Install

Assrt ships as a single npm package. Install it globally or per-project:

bash
# global
npm install -g @assrt/cli

# or per-project
npm install --save-dev @assrt/cli
Requirements
Node.js 20 or later, and a supported OS (macOS, Linux, or Windows). Browser binaries are installed in the next step.

2. Initialize a project

Run assrt init in the root of the repository you want to test. It creates a config file and a tests directory.

bash
assrt init
# creates ./assrt.config.yaml and ./tests/

3. Install browsers

Download the browsers the CLI will drive. This is a one-time step per machine.

bash
assrt install-browsers

4. Author your first test

Tests are YAML files with a name, a target URL, and a list of steps. Each step is either a concrete action (click, type, navigate) or a natural-language instruction that Assrt resolves at runtime.

tests/login.yamlyaml
name: User can log in
url: https://app.example.com

steps:
  - navigate: /login
  - type:
      element: email input
      text: qa@example.com
  - type:
      element: password input
      text: "{{ env.TEST_PASSWORD }}"
  - click: sign in button
  - ai-check: the dashboard is visible

5. Run it

bash
assrt run tests/login.yaml

Assrt opens a browser, executes each step in order, and prints a pass or fail summary. Screenshots and a trace of every step are written to ./assrt-results/.

Next steps

  1. Read Finding Elements to write locators that survive UI changes.
  2. Read Writing Assertions to turn expectations into reliable checks.
  3. Wire the CLI into CI with the GitHub Actions guide.