Getting Started

Get up and running with ShipTested in under 5 minutes. This guide walks you through installation, authentication, and generating your first test suite.

Requirements#

ShipTested requires Node.js 18 or later. You can check your version by running:

node --version

Installation#

Install ShipTested globally via npm, or run it directly with npx.

Global install#

npm install -g shiptested

Or use npx (no install needed)#

npx shiptested [command]

If you install globally, you can run shiptested directly from any directory. With npx, the CLI is downloaded and executed on the fly.

Authentication#

ShipTested uses GitHub OAuth for authentication. Run the login command to connect your account:

shiptested login

This will:

Open your browser to the GitHub authorization page
Start a local server to receive the OAuth callback
Store your credentials at ~/.shiptested/credentials

The login flow has a 2-minute timeout. If authentication does not complete in time, run the command again.

For CI/CD environments, use an API key instead of OAuth. See the CI/CD Integration guide.

Project Setup#

Navigate to your project directory and initialize ShipTested:

cd your-project
shiptested init

The init command analyzes your project and creates a shiptested.config.ts file with smart defaults based on your stack. It detects your language, framework, test runner, and module system automatically.

If a config file already exists, use --force to overwrite it:

shiptested init --force

Generate Your First Tests#

With authentication and config in place, you are ready to generate tests:

shiptested generate

ShipTested will scan your project, identify testable files, and generate test suites that actually pass. The CLI runs tests locally on your machine and iterates until they pass or the maximum number of iterations is reached.

You can also target specific files:

shiptested generate --files src/utils/helpers.ts

Quick Example#

Here is a full workflow from start to finish:

# Install globally
npm install -g shiptested

# Authenticate with GitHub
shiptested login

# Navigate to your project
cd ~/projects/my-app

# Initialize config
shiptested init

# Generate tests for the entire project
shiptested generate

# Or generate tests for specific files
shiptested generate --files src/lib/utils.ts

# Check your test coverage
shiptested coverage

# View results in the dashboard
shiptested dashboard

Example terminal output during generation:

$ shiptested generate --files src/lib/utils.ts

  Analyzing project...
  Detected: TypeScript + React + Vitest

  Generating tests for src/lib/utils.ts
  ├─ Iteration 1: 4/6 tests passing
  ├─ Iteration 2: 5/6 tests passing
  └─ Iteration 3: 6/6 tests passing ✓

  Results:
  Files tested:  1
  Tests passing: 6/6
  Coverage:      94%

  Results reported to dashboard.

Next Steps#

CLI Reference – explore all commands and flags
Configuration – customize test generation for your project
How It Works – understand the generation pipeline
CI/CD Integration – automate test generation in your pipeline

Was this page helpful?

CLI Reference