SYSTEM INITIALIZING...
+1 (919) 375-3696 sales@aspectiq.ai
Support

Exclusive Access Required

Please enter your corporate email address to access the technical documentation. Personal email addresses are not accepted.

Developer Docs

Build faster with clear, guided documentation.

Quick start, API reference, integrations, and advanced guides for teams shipping on AspectIQ.

Get Started Browse API
Quick Start API Reference Integrations Troubleshooting
Read Time 5 min

Start with the quick setup, then move into configuration and test execution.

Coverage 100+

Commands, examples, and integration paths across the product surface.

Help Always on

Use the table of contents and sidebar to jump between sections instantly.

DocsGetting StartedQuick Start
Quick Start

Get started in 5 minutes

Set up AspectIQ, record your first test, and run it on our cloud infrastructure — all without writing a single line of code.

5 min read v3.2.1 Updated Mar 28, 2026
Prerequisites
You need an AspectIQ account (free trial available), Node.js 18+ for CLI usage, and access to a web browser. No Selenium or WebDriver installation needed.

Step 1: Install the AspectIQ CLI

The AspectIQ CLI lets you run tests, manage configurations, and push results from your terminal or CI pipeline.

npm
yarn
Homebrew
Docker
bashterminal
# Install globally
npm install -g @aspectiq/cli

# Verify installation
aspectiq --version
# → aspectiq v3.2.1
bashterminal
yarn global add @aspectiq/cli
bashterminal
brew tap aspectiq/tap
brew install aspectiq
bashterminal
docker pull aspectiq/runner:latest

Step 2: Authenticate

Run the login command to authenticate the CLI with your AspectIQ account. This stores a token in ~/.aspectiq/credentials.

bashterminal
aspectiq auth login

# Or pass your API key directly (useful for CI/CD)
aspectiq auth login --api-key YOUR_API_KEY

# Confirm authentication
aspectiq auth whoami
# → Authenticated as jane@yourcompany.com (Org: Acme Corp)
Finding your API key
Navigate to Settings → API Keys in the AspectIQ dashboard. Create a key with appropriate scopes — runs:write for CI usage, admin for full access.

Step 3: Initialize a Project

Create an AspectIQ project configuration in your repository. This file defines project-level settings like timeouts, retries, and environment variables.

bashterminal
cd your-project
aspectiq init

# This creates aspectiq.config.yml in your current directory

The generated config file looks like this:

yamlaspectiq.config.yml
project:
  name: my-project
  id: proj_xxxxxxxxxxxxxxxx

defaults:
  browser: chrome        # chrome | firefox | safari | edge
  timeout: 30000          # ms per step
  retries: 2              # retry count on flake
  headless: true

environments:
  staging:
    base_url: https://staging.yourapp.com
  production:
    base_url: https://yourapp.com

ai:
  self_healing: true     # enable AI self-healing
  healing_confidence: 0.85 # min match confidence

Step 4: Record Your First Test

Open the AspectIQ recorder to capture a test by interacting with your app in a real browser. No scripting needed.

bashterminal
aspectiq record --name "Login Flow" --env staging

# A browser window opens. Interact naturally with your app.
# Click, type, assert — AspectIQ captures everything.
# Press Ctrl+S or click "Save" in the toolbar when done.
# → Test saved: tests/login-flow.aspect
Chrome Extension Required
Install the AspectIQ Chrome Extension before recording. It provides enhanced element capture, smarter locator generation, and the recorder toolbar.

Step 5: Run the Test

Execute your recorded test locally or push it to AspectIQ's cloud infrastructure for parallel cross-browser execution.

bashterminal
# Run a specific test
aspectiq run tests/login-flow.aspect

# Run all tests in a directory
aspectiq run tests/

# Run on cloud with specific browsers
aspectiq run tests/ --cloud --browsers chrome,firefox,safari

# Run with a specific environment
aspectiq run tests/ --env staging

After a successful run, you'll see output like:

textoutput
  AspectIQ Test Runner v3.2.1
  ──────────────────────────────────────
  Running: Login Flow
  Browser: Chrome 124 · Headless
  Environment: staging

  ✓  Navigate to /login                         142ms
  ✓  Fill email field                             88ms
  ✓  Fill password field                          62ms
  ✓  Click "Sign In" button                      234ms
  ✓  Assert: Dashboard heading visible            44ms
  ✓  Assert: User avatar displayed                38ms

  ──────────────────────────────────────
  ✓  6 steps passed · 0 failed · 608ms total
  →  Report: https://app.aspectiq.com/runs/run_a1b2c3

Configuration Reference

Full list of configuration options available in aspectiq.config.yml:

KeyTypeDefaultRequiredDescription
project.idstring—RequiredYour AspectIQ project ID
defaults.browserstringchromeOptionalDefault browser for test runs
defaults.timeoutnumber30000OptionalPer-step timeout in milliseconds
defaults.retriesnumber2OptionalNumber of retry attempts on failure
ai.self_healingbooleantrueOptionalEnable AI-powered self-healing
ai.healing_confidencenumber0.85OptionalMinimum confidence score (0–1) for element matching

What's Next?

Now that you've run your first test, explore the rest of the documentation:

Previous
Introduction