Skip to main content
The QAOS config file is a JSON document that fully specifies a test run. Save it anywhere on your system and pass its path to qaos run --config.

​
Full example

qaos-config.json
{
  "name": "Full Site Audit — v2.1",
  "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "envFile": ".env.test",
  "agentInfo": {
    "environment": "staging",
    "triggeredBy": "ci-pipeline",
    "branch": "main"
  },
  "tasks": [
    {
      "id": "auth-login",
      "description": "Navigate to the login page and sign in with credentials admin@example.com / password123",
      "context": "Use the test account. The login page has a standard username/password form.",
      "startUrl": "https://staging.example.com/login",
      "subAgents": ["security", "uiux"]
    },
    {
      "id": "dashboard",
      "description": "Browse the main dashboard and interact with the data tables",
      "startUrl": "https://staging.example.com/dashboard",
      "subAgents": ["security", "uiux"]
    },
    {
      "id": "admin-panel",
      "description": "Access the admin panel and attempt to perform admin actions as a regular user",
      "startUrl": "https://staging.example.com/admin",
      "subAgents": ["security"]
    },
    {
      "id": "user-settings",
      "description": "Navigate to user account settings, edit the profile, and change the password",
      "startUrl": "https://staging.example.com/settings",
      "subAgents": ["security", "uiux"]
    }
  ]
}

​
Root-level fields

​
name required

Type: string A human-readable label for this run, shown in the dashboard and reports. Use descriptive names that identify the scope and context. 
"name": "Production security audit — Q1 2025"

​
projectId required

Type: string (UUID) The ID of the QAOS project this run belongs to. Find project IDs in the Dashboard under Projects → Settings. 
"projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
envFile optional

Type: string Path to a .env file to load before the run starts. Useful for injecting credentials, API URLs, or environment-specific values. 
"envFile": ".env.staging"
The path is resolved relative to the config file’s location.

​
agentInfo optional

Type: object Arbitrary key-value metadata attached to the run and visible in the report. Use this to track context like environment name, CI pipeline info, or triggering user. 
"agentInfo": {
  "environment": "staging",
  "commit": "abc1234",
  "triggeredBy": "github-actions"
}

​
tasks required

Type: array The list of test tasks to execute. Tasks run sequentially in the order they are defined. At least one task is required.

​
Task fields

Each object in the tasks array:

​
id required

Type: string A unique identifier for this task within the run. Used in logs and reports. Must be unique across all tasks in the same config. 
"id": "checkout-flow"

​
description required

Type: string A natural language description of what this task should do. The agent interprets this to decide which actions to take, which pages to navigate to, and what to look for. More specific descriptions yield better results. 
"description": "Go to the checkout page, add item #SKU-001 to the cart, proceed to payment, and check the payment form for security issues"

​
context optional

Type: string Additional background information the agent should be aware of when executing this task. Useful for providing credentials, explaining application-specific behavior, or flagging known limitations. 
"context": "Use test credentials test@example.com / testpass123. The dashboard may take 2-3 seconds to load data."

​
startUrl required

Type: string The URL the agent navigates to at the beginning of this task. Must be a valid absolute URL including protocol. 
"startUrl": "https://app.example.com/login"

​
subAgents required

Type: array of "security" | "uiux" Which agent modules to activate for this task. Accepts an array containing one or both values. 
"subAgents": ["security", "uiux"]  // run both
"subAgents": ["security"]             // security only
"subAgents": ["uiux"]              // UI/UX only
AgentWhat it checks
"security"Access control, injection, cryptography, session management, information disclosure
"uiux"Accessibility, form usability, keyboard navigation, color contrast, responsive design

​
Common patterns

​
Multi-step authentication flow

{
  "tasks": [
    {
      "id": "login",
      "description": "Log in with username admin@example.com and password TestPass123",
      "startUrl": "https://app.example.com/login",
      "subAgents": ["security", "uiux"]
    },
    {
      "id": "post-login",
      "description": "Browse the authenticated dashboard and user profile page",
      "startUrl": "https://app.example.com/dashboard",
      "subAgents": ["security", "uiux"]
    }
  ]
}

​
Security-focused admin audit

{
  "tasks": [
    {
      "id": "admin-access",
      "description": "Try to access the admin panel at /admin without authentication",
      "startUrl": "https://app.example.com/admin",
      "subAgents": ["security"]
    },
    {
      "id": "privilege-check",
      "description": "Log in as a regular user and attempt to access admin-only endpoints",
      "startUrl": "https://app.example.com/login",
      "context": "Regular user credentials: user@example.com / UserPass123",
      "subAgents": ["security"]
    }
  ]
}

​
Accessibility-only quality pass

{
  "tasks": [
    {
      "id": "homepage-a11y",
      "description": "Review the homepage for accessibility issues",
      "startUrl": "https://app.example.com/",
      "subAgents": ["uiux"]
    },
    {
      "id": "forms-a11y",
      "description": "Navigate through the registration form and contact form for accessibility issues",
      "startUrl": "https://app.example.com/register",
      "subAgents": ["uiux"]
    }
  ]
}