Getting Started

Quick Start

Qualigate lets you write end-to-end tests in plain English and have an AI agent execute them in a real browser. No test framework to learn, no selectors to maintain, no code to write. Here is the shortest path to your first test result:

Step 1: Create an Account

Sign up at qualigate.app using your email or a Google/GitHub account. The free tier gives you 15 credits during your trial period (5 credits per month afterward), which is enough to run several tests and evaluate the platform.

After signing up, you will be guided through the onboarding wizard where you set up your first project.

Step 2: Add Your Project

A project represents the web application you want to test. You need to provide:

• Project name — A descriptive label (e.g., "My E-commerce Site")
• Base URL — The root URL of your application (e.g., https://staging.mysite.com)
• Environment — Staging, production, development, or custom

If your application requires authentication, you can add login credentials securely in Project Settings > Credentials. Credentials are encrypted at rest using Supabase Vault (AES-256-GCM) and never exposed in test step definitions.

Step 3: Write Your First Test

Qualigate uses natural language to define tests. Describe what you want the AI to do in plain English, one step per line. Here is an example login test:

1. Navigate to the login page
2. Enter "user@example.com" in the email field
3. Enter "password123" in the password field
4. Click the "Sign In" button
5. Verify that the dashboard page loads
6. Verify that a welcome message is visible

The AI interprets each step, finds the matching elements on the page, and executes the action. You do not need to specify CSS selectors, XPaths, or test IDs.

Tips for Effective Test Steps

• Start with an action verb — Navigate, Click, Type, Select, Verify, Scroll, Wait, Press
• Use quoted strings for exact values — Enter "user@test.com" rather than "Enter an email address"
• End with assertions — Always include at least one Verify that... step to confirm the expected outcome
• Reference visible text — Say "Click the Submit button" rather than "Click the element with class btn-primary"

More Examples

# E-commerce search flow
1. Navigate to https://myshop.com
2. Type "wireless headphones" into the search bar
3. Press Enter
4. Verify that search results appear
5. Click the first product in the results
6. Verify that the product detail page loads
7. Click "Add to Cart"
8. Verify that the cart count shows "1"

# Form validation test
1. Navigate to the registration page
2. Leave the email field empty
3. Click the "Sign Up" button
4. Verify that an error message about email is displayed
5. Enter "invalid-email" in the email field
6. Click the "Sign Up" button
7. Verify that a format validation error appears

Step 4: Run Your Test

Click the Run button on your test case page. Qualigate will:

1. Launch a Chromium browser in the cloud
2. Start video recording
3. Read the first step and analyze the page
4. Execute the action (click, type, navigate, etc.)
5. Take a screenshot
6. Repeat for each subsequent step
7. Upload the video recording and mark the test as passed or failed

Most tests complete in 1–3 minutes. You can watch the status update in real time on the test run page.

Step 5: Understanding Results

After a test completes, the run detail page shows:

Step 6: Get Your API Key

To trigger tests programmatically (from CI/CD, scripts, or the CLI), you need an API key:

1. Go to Settings > API Keys in your Qualigate dashboard
2. Click Generate New Key
3. Give your key a descriptive name (e.g., "CI/CD Pipeline")
4. Copy the key (it starts with qg_)

Step 7: Trigger a Test via API

Use the REST API to trigger a test run. You can authenticate with either the Authorization: Bearer header or the X-API-Key header.

curl -X POST https://qualigate.app/api/v1/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "test_case_id": "your-test-case-uuid",
    "context": {
      "source": "github-actions",
      "branch": "main",
      "sha": "abc123def456"
    }
  }'

Response

{
  "success": true,
  "test_run_id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Test run queued successfully"
}

You can also trigger all tests in a suite or project by passing test_suite_id or project_id instead. See the API Reference for the full request and response specifications.

Step 8: Check Results via API

Poll the status endpoint to check if your test has finished:

curl https://qualigate.app/api/v1/trigger?test_run_id=YOUR_TEST_RUN_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes the current status (pending, running, passed, failed, error, or timeout), duration, step count, and a link to the video recording.

Example: Polling in a Shell Script

#!/bin/bash
# Trigger test and capture the run ID
RESPONSE=$(curl -s -X POST https://qualigate.app/api/v1/trigger \
  -H "Authorization: Bearer $QUALIGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"test_case_id": "your-test-case-uuid"}')

RUN_ID=$(echo $RESPONSE | jq -r '.test_run_id')
echo "Test run started: $RUN_ID"

# Poll until complete (max 60 attempts, 10s apart = 10 min)
for i in $(seq 1 60); do
  RESULT=$(curl -s \
    -H "Authorization: Bearer $QUALIGATE_API_KEY" \
    "https://qualigate.app/api/v1/trigger?test_run_id=$RUN_ID")
  STATUS=$(echo $RESULT | jq -r '.status')
  echo "[$i] Status: $STATUS"

  if [ "$STATUS" = "passed" ]; then
    echo "Test passed!"
    exit 0
  elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "error" ]; then
    echo "Test failed: $(echo $RESULT | jq -r '.error_message // "See dashboard for details"')"
    exit 1
  fi

  sleep 10
done

echo "Timed out waiting for test results"
exit 1

Next Steps

Now that you have run your first test, explore these resources to go further:

• API Reference — Full endpoint documentation with request/response examples for triggering tests, checking results, and retrieving CI/CD configuration
• CLI Guide — Run and manage tests directly from your terminal
• GitHub Actions Integration — Production-ready workflow file to run Qualigate tests on every push and pull request
• MCP Server — Connect Qualigate to Claude and other AI development tools
• Best Practices for Natural Language Tests — Five patterns that make your tests more reliable and maintainable