Quick Start

View as Markdown

Set up Shiplight in your coding agent, then create and run your first browser test.

Step 1: Install Shiplight

Shiplight uses skills to guide your coding agent and an MCP server to give it access to a real browser. Choose your coding agent below, run the command in your terminal, and then restart the agent.

Choose your coding agent

Each command installs everything the selected agent needs. You can copy and paste it as written.

npx -y skills add ShiplightAI/agent-skills-v2 -a claude-code -y && \
npx -y add-mcp "npx -y @shiplightai/mcp@latest" -n shiplight --env PWDEBUG=console -a claude-code -y

Use another coding agent

If your coding agent is not listed above, you can still install the Shiplight skills. Replace <agent> with the name used by your agent:

npx -y skills add ShiplightAI/agent-skills-v2 -a <agent> -y

See the full list of supported agents to find the correct name.

Set up the MCP server manually

If add-mcp does not support your agent, add the MCP server to the agent's configuration file yourself. Check your agent's documentation to find the file, then add:

{
  "mcpServers": {
    "shiplight": {
      "command": "npx",
      "args": ["-y", "@shiplightai/mcp@latest"],
      "env": {
        "PWDEBUG": "console"
      }
    }
  }
}

Keep Shiplight up to date

The MCP server uses the latest release automatically. To update the Shiplight skills installed on your computer, run the command that matches how you installed them:

npx -y skills update -p   # project-level
npx -y skills update -g   # user-level (global)

Step 2: Create your first test

Use the /shiplight command

In your coding agent, type /shiplight followed by the task you want to run. For example: /shiplight verify, /shiplight create-yaml-tests, or /shiplight fix. Run /shiplight help to see every available command, or /shiplight help <command> to learn more about one command. See Agent-Driven Testing for the full list.

Set up your test project

Open your application's repository in your coding agent, then run /shiplight init. Shiplight creates the test structure, installs the required packages, and adds specs/context.md for information about your application.

Set up login (if your app needs it)

If your application requires users to sign in, run /shiplight auth. Shiplight saves a signed-in browser session so your tests can start behind the login screen. See Authentication for other ways to test signed-in pages.

Create a test

Tell your coding agent what you want to test. You can use /shiplight create-yaml-tests or write the request naturally. Your agent recognizes the request, walks through your application in a real browser, and writes a YAML E2E test that you can read and review.

/shiplight create yaml tests for the login flow at localhost:3000

Run the test

Run the following command in your terminal:

npx shiplight test

When the test finishes, open shiplight-report/index.html. The report shows whether each step passed or failed, along with screenshots and traces. See Report to change what Shiplight saves.

Step 3: Fix failing tests

If a test fails after you change your application, run /shiplight fix. Your coding agent reproduces the failure, finds the cause, and updates the YAML test when the test is out of date. If the application has a bug, it reports the problem without changing the test. Shiplight handles most outdated element locators automatically while a test runs; see How self-healing works.

Use /shiplight fix to repair failing tests in ./tests after the latest deployment.

For more complex flows, use the local debugger to run the test one step at a time, review screenshots and traces, and edit the YAML yourself. See Fix a failing test for the complete process.

Step 4: Run in CI (optional)

You can run the same YAML E2E tests in GitHub Actions, GitLab CI, CircleCI, Jenkins, and other CI services. Read Where tests run to compare your own CI runners with Shiplight-hosted runners, then follow the CI/CD guide to set up your workflow.

Check UI changes as you work

After your coding agent changes the user interface, run /shiplight verify. The agent opens your application in a browser and confirms that the change works. You do not need to create a test file first.

Update the navbar to include "Pricing" and "Blog" links, then use /shiplight verify to confirm they appear correctly on localhost:3000.

Next steps

• Guides — Follow step-by-step instructions for common testing tasks.
• YAML E2E test format — Learn how to read and edit Shiplight test files.
• Run locally — Run tests on your computer and review the results.
• CI/CD — Run your tests automatically with your CI provider.
• Shiplight Cloud — Upload results, track flaky tests, and manage CI runners, API tokens, and billing.