---
title: Debugging
description: Launch the Shiplight visual debugger to browse tests, step through statements, inspect the browser, and hand-tune complex YAML E2E flows.
---

# Debugging

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

The `npx shiplight debug` command launches a visual debugger for YAML E2E test files. It opens a local web UI where you can browse tests, step through statements, inspect the browser, and edit YAML — the human-in-the-loop path for hand-tuning complex UI tests.

```bash
npx shiplight debug                                    # browse current directory
npx shiplight debug tests/                             # browse tests/ directory
npx shiplight debug tests/login.test.yaml              # open a specific test
npx shiplight debug tests/login.test.yaml --open       # open and launch browser
```

## Create a New Test

Use `--new` to create a test file and start debugging immediately:

```bash
npx shiplight debug tests/checkout.test.yaml --new --url https://myapp.com/checkout
```

This creates the file with a starter template if it doesn't exist, then opens the debugger.

## Options

| Option        | Description                              | Default |
| ------------- | ---------------------------------------- | ------- |
| `--port <n>`  | Server port                              | 6174    |
| `--url <url>` | Starting URL for new tests               | —       |
| `--new`       | Create the test file if it doesn't exist | —       |
| `--open`      | Auto-open the debugger in your browser   | —       |
| `--no-open`   | Don't auto-open the browser              | default |

The debugger auto-detects your `playwright.config.ts` and uses its settings (browser, baseURL, auth, etc.). If no config is found, it runs in standalone mode with a built-in browser sandbox.