Your First Test in 10 Minutes¶

Quorvex UI flow for getting started with the dashboard.

In this tutorial, you will install Quorvex AI, write a test spec in plain English, run it through the AI pipeline, and see a fully generated, passing Playwright test.

Prerequisites¶

Step 1: Clone the Repository¶

Open a terminal and clone the project:

git clone https://github.com/NihadMemmedli/quorvex_ai.git
cd quorvex_ai

You should see the project structure:

quorvex_ai/
  orchestrator/     # Python backend
  web/              # Next.js frontend
  specs/            # Test specifications
  tests/generated/  # Output: generated Playwright tests
  Makefile          # All project commands
  ...

Step 2: Install and Start¶

cp .env.prod.example .env.prod

make dev

make setup

[1/7] Checking prerequisites...
  + Python 3.12
  + Node.js v20.11.0
  + npm 10.2.4
[2/7] Setting up environment configuration...
[3/7] Setting up Python virtual environment...
[4/7] Installing Python dependencies...
[5/7] Installing root Node.js dependencies...
[6/7] Installing Playwright browsers...
[7/7] Setting up Web Dashboard...
Setup Complete!

make check-env
make dev

Step 3: Configure Your API Key¶

Quorvex AI uses an AI model to generate tests. Open the environment file for your setup path and add your API credentials:

# Required: AI/LLM configuration
QUORVEX_LLM_PROVIDER=anthropic_compatible
QUORVEX_LLM_API_KEY=your-api-token-here
QUORVEX_LLM_BASE_URL=https://api.z.ai/api/anthropic
QUORVEX_LLM_LIGHT_MODEL=glm-4.5-air
QUORVEX_LLM_STANDARD_MODEL=glm-5-turbo
QUORVEX_LLM_DEEP_MODEL=glm-5.1
QUORVEX_LLM_TOOL_DEEP_MODEL=glm-5.1
QUORVEX_LLM_CHAT_MODEL=glm-5-turbo
API_TIMEOUT_MS=3000000

make prod-restart

# Required: AI/LLM configuration
QUORVEX_LLM_PROVIDER=anthropic_compatible
QUORVEX_LLM_API_KEY=your-api-token-here
QUORVEX_LLM_BASE_URL=https://api.z.ai/api/anthropic
QUORVEX_LLM_LIGHT_MODEL=glm-4.5-air
QUORVEX_LLM_STANDARD_MODEL=glm-5-turbo
QUORVEX_LLM_DEEP_MODEL=glm-5.1
QUORVEX_LLM_TOOL_DEEP_MODEL=glm-5.1
QUORVEX_LLM_CHAT_MODEL=glm-5-turbo
API_TIMEOUT_MS=3000000

Replace your-api-token-here with your actual API token.

Validate your configuration:

make check-env

Expected output:

Checking environment configuration...

  + .env file exists
  + QUORVEX_LLM_API_KEY is configured
  + QUORVEX_LLM_BASE_URL: https://api.z.ai/api/anthropic
  + Model: glm-5.1
  - OPENAI_API_KEY not set (memory system limited)

  + Python virtual environment exists
  + Frontend dependencies installed

make check-env reads .env and, when present, .env.prod. Docker users should confirm the .env.prod section shows configured production secrets before starting or restarting the stack.

Step 4: Write a Test Spec¶

A test spec is a markdown file that describes what to test in plain English. Create your first spec:

cat > specs/my-first-test.md << 'EOF'
# Test: Hello World Check

## Description
Verify that the dynamic loading example on the-internet.herokuapp.com works correctly.

## Steps
1. Navigate to https://the-internet.herokuapp.com/dynamic_loading/1
2. Click the "Start" button
3. Wait for the loading to complete
4. Verify the text "Hello World!" is visible

## Expected Outcome
- The "Hello World!" message is displayed after loading completes
EOF

The spec format has three required sections:

Step 5: Run the Pipeline¶

Run your spec through the AI pipeline:

make run SPEC=specs/my-first-test.md

Or use the CLI directly (local setup only):

source venv/bin/activate
python orchestrator/cli.py specs/my-first-test.md

The pipeline has three stages:

1. Planning -- the AI reads your spec and creates a structured test plan (target URL, steps, assertions).
2. Generation -- the AI opens a real browser, explores the target page, and writes Playwright test code.
3. Healing -- if the generated test fails, the AI debugs it using browser tools (up to 3 attempts).

You should see the pipeline progress through all three stages and finish with Status: passed. The generated test file is saved to tests/generated/hello-world-check.spec.ts.

Step 6: Inspect the Generated Test¶

Open the generated test file to see what the AI produced:

cat tests/generated/hello-world-check.spec.ts

You should see a complete Playwright test similar to:

import { test, expect } from '@playwright/test';

test('Hello World Check', async ({ page }) => {
  // Step 1: Navigate to the dynamic loading page
  await page.goto('https://the-internet.herokuapp.com/dynamic_loading/1');

  // Step 2: Click the Start button
  await page.getByRole('button', { name: 'Start' }).click();

  // Step 3-4: Wait for and verify "Hello World!" text
  await expect(page.getByText('Hello World!')).toBeVisible({ timeout: 30000 });
});

Notice that the AI:

• Used resilient selectors (getByRole, getByText) instead of brittle CSS selectors
• Added an appropriate timeout for the dynamic loading
• Mapped your English steps to real Playwright API calls

Step 7: Run the Test Directly¶

You can re-run the generated test anytime without going through the pipeline:

npx playwright test tests/generated/hello-world-check.spec.ts

Expected output:

Running 1 test using 1 worker

  PASSED  hello-world-check.spec.ts (3.8s)

  1 passed (4.1s)

Add --headed to watch the browser execute the test visually.

Step 8: Review Pipeline Artifacts¶

Every pipeline run produces artifacts in the runs/ directory:

ls runs/2026-03-01_10-00-00/

plan.json           # Structured test plan from Stage 1
export.json         # Generated code metadata from Stage 2
spec.md             # Copy of your spec
status.txt          # Final result: "passed" or "error"

Inspect plan.json to see the AI's interpretation of your spec -- it contains the target URL, test name, and structured steps.

Step 9: Try a Second Test¶

Now write a slightly more complex spec:

cat > specs/form-validation-test.md << 'EOF'
# Test: Form Authentication

## Description
Test the login form on the-internet.herokuapp.com with valid credentials.

## Steps
1. Navigate to https://the-internet.herokuapp.com/login
2. Enter "tomsmith" into the Username field
3. Enter "SuperSecretPassword!" into the Password field
4. Click the "Login" button
5. Verify the page displays "You logged into a secure area!"

## Expected Outcome
- The user is redirected to the secure area after login
- A success message is displayed
EOF

Run it:

make run SPEC=specs/form-validation-test.md

This test exercises form filling and navigation, demonstrating that the AI handles multi-step interactions.

Step 10: Run All Generated Tests¶

After generating multiple tests, run them all at once:

npx playwright test

This runs every .spec.ts file in the tests/generated/ directory.

Managing Services (Docker)¶

If you used the Docker setup, these commands help you manage the environment:

What You Learned¶

In this tutorial, you:

• Installed Quorvex AI using Docker (make dev)
• Configured API credentials in .env.prod (Docker) or .env (local)
• Wrote a test spec in plain English markdown
• Ran the Pipeline to generate a Playwright test
• Inspected the generated test code and pipeline artifacts
• Ran the generated test directly with Playwright
• Created a second test to see multi-step interactions

Next Steps¶

• Dashboard Walkthrough -- manage specs and runs through the web UI
• Your First API Test -- generate HTTP API tests without a browser
• App Exploration and Requirements -- let AI discover your app automatically
• Writing Specs -- full spec format reference with templates and credentials
• Environment Variables -- configure timeouts, browsers, and more