---
sidebar_position: 5
title: Running Tests
---

# Running Tests

Zibby runs tests locally using an AI agent that drives a real browser. It records video, captures actions, and generates reusable Playwright scripts.

## Basic Usage

```bash
zibby test test-specs/login.txt --agent cursor
```

## From a Test Spec File

Create a plain-text file with test steps:

```text title="test-specs/login.txt"
1. Navigate to the login page
2. Enter email: test@example.com
3. Enter password: TestPass123
4. Click the Sign In button
5. Verify the dashboard page loads
6. Verify the user's name appears in the header
```

Run it:

```bash
zibby test test-specs/login.txt
```

## From Cloud Test Cases

After running analysis on a Jira ticket in the dashboard:

```bash
zibby test --sources TC001,TC002 --execution abc-123-def --sync
```

## What Happens During a Run

The default workflow executes three nodes:

1. **Preflight** — AI extracts a title and assertions from the test spec
2. **Execute Live** — AI drives a Playwright browser, following the test steps
3. **Generate Script** — AI produces a reusable `.spec.js` from recorded actions

```
Test Spec → Preflight → Execute Live → Generate Script → Done
```

## Choosing an AI Agent

```bash
# Cursor Agent (uses Cursor IDE or CURSOR_API_KEY)
zibby test test-specs/login.txt --agent cursor

# Claude (uses ANTHROPIC_API_KEY)
zibby test test-specs/login.txt --agent claude

# Codex (uses OPENAI_API_KEY + codex CLI)
zibby test test-specs/login.txt --agent codex
```

## Headless Mode

Run without a visible browser (for CI/CD):

```bash
zibby test test-specs/login.txt --headless
```

## Cloud Sync

Upload results to the [Zibby dashboard](https://zibby.app):

```bash
# Upload to dashboard
zibby test test-specs/login.txt --sync

# Organize into a collection
zibby test test-specs/login.txt --collection "Auth Tests" --sync

# With subfolder
zibby test test-specs/login.txt --collection "Auth Tests" --folder "Login" --sync

# Local only (no upload)
zibby test test-specs/login.txt --no-sync
```

The `cloudSync` setting in `.zibby.config.js` sets the default. CLI flags override it.

## Running a Single Node

Re-run just one step of the workflow (useful for debugging):

```bash
# Re-execute the browser test (reusing previous session)
zibby test test-specs/login.txt --node execute_live --session last

# Only regenerate the Playwright script
zibby test test-specs/login.txt --node generate_script --session last
```

## Custom Workflows

If you've created a custom workflow in `.zibby/graph.js`:

```bash
zibby test test-specs/login.txt --workflow QuickSmokeWorkflow
```

Supported formats: `QuickSmokeWorkflow`, `QuickSmoke`, `quick-smoke`.

## Opening Results in Browser

```bash
zibby test test-specs/login.txt --sync --open
```

The `--open` flag opens the dashboard results page after upload.

## Debugging

```bash
# Info-level logs
zibby test test-specs/login.txt --verbose

# Full debug logs
zibby test test-specs/login.txt --debug
```