Skip to main content

Agnox - Integration Quickstart

Connect your test automation project to the platform and run your first test in minutes.

Agnostic Deployment with Agnox CLI​

The Agnox CLI provides a Zero-Config experience through Deep Analysis of your project. It starts by collecting your Docker Hub identity and deep-scans your local configuration (package.json, requirements.txt, or pyproject.toml) for smart version pinning. With its platform intelligence, it automatically detects browser channels, reporting tools, and system dependencies, eliminating "it works on my machine" issues by proactively warning and adjusting for platform constraints.

Key Features:

  • Automated Infrastructure Sync: Deep framework analysis to pin base images to your exact local versions.
  • Multi-Platform Buildx Execution: Intelligent platform adjustment (e.g., forcing linux/amd64 for proprietary browser channels) for seamless cross-platform deployments.
  • AI-Powered Root Cause Integration: Automatic configuration of reporting tools (like Allure) to ensure rich data for downstream AI debugging.
npx @agnox/agnox-cli@latest init

Next Steps: If you choose manual deployment, the CLI generates personalized docker buildx commands and instructions that are specific to your Docker Hub identity and copy-paste ready.

Manual Setup​

Prerequisites​

  • Docker Hub account with a pushed automation image
  • Platform account at agnox.dev

Step 1: Prepare Your Project​

Your automation container must follow the Container Protocol. At minimum, you need:

1.1 Create entrypoint.sh​

#!/bin/sh
FOLDER_PATH=$1
echo "🚀 Starting Agnostic Automation..."

# Handle environment enforcement
if [ -f .env ]; then
    echo "🧹 Removing local .env to enforce Worker configuration..."
    rm .env
fi

# Execution Logic
if [ -z "$FOLDER_PATH" ] || [ "$FOLDER_PATH" = "all" ]; then
    echo "▶️ Running ALL tests against $BASE_URL..."
    npx playwright test
else
    echo "▶️ Running tests in: $FOLDER_PATH against $BASE_URL..."
    npx playwright test "$FOLDER_PATH"
fi

# Report Generation
echo "📊 Generating Allure Report..."
npx allure generate allure-results --clean -o allure-report

1.2 Create Dockerfile​

FROM mcr.microsoft.com/playwright:v1.40.0-jammy
WORKDIR /app

COPY package*.json ./
RUN npm ci
RUN npm install -g allure-commandline

COPY . .
RUN chmod +x /app/entrypoint.sh

# ⚠️ IMPORTANT: Do NOT add ENTRYPOINT or CMD
# The agnox Worker injects the entrypoint at runtime to handle environment variables 
# and log streaming. Adding them here will conflict with the execution engine.

⚠️ Do not add ENTRYPOINT or CMD to your Dockerfile. The Worker injects the entrypoint at runtime - adding them will conflict with the execution engine.

1.3 Configure Your Framework​

Ensure your test framework reads BASE_URL from environment:

playwright.config.ts:

export default defineConfig({
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
  },
  reporter: [
    ['html', { outputFolder: 'playwright-report' }],
    ['allure-playwright', { outputFolder: 'allure-results' }],
  ],
});

Step 2: Build & Push Your Image​

# Build your image
docker build -t your-dockerhub-user/my-automation:latest .

# Push to Docker Hub
docker push your-dockerhub-user/my-automation:latest

Step 3: Register on the Platform​

  1. Go to https://agnox.dev
  2. Click Sign Up and create your account
  3. Your organization is created automatically (you're the admin)

Step 4: Generate an API Key​

For CI/CD integration, generate an API Key (no username/password required):

  1. Login to https://agnox.dev
  2. Go to Settings → Profile
  3. Scroll to API Access section
  4. Click Generate New Key
  5. Give it a name (e.g., "GitHub Actions")
  6. Copy the key immediately - it's only shown once!

Store the API key securely in your CI/CD secrets (e.g., AAC_API_KEY).

Step 5: Execute Tests​

Option A: Via Dashboard​

  1. Login to https://agnox.dev
  2. Click "Run"
  3. Enter your Docker image name
  4. Select environment and folder
  5. Click Run

Option B: Via API​

curl -X POST "https://api.agnox.dev/api/executions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "your-dockerhub-user/my-automation:latest",
    "command": "npx playwright test",
    "environment": "staging",
    "baseUrl": "https://staging.agnox.dev",
    "folder": "tests/e2e"
  }'

Option C: CI/CD Integration (GitHub Actions)​

name: Run E2E Tests
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Tests
        run: |
          curl -X POST https://api.agnox.dev/api/executions \
            -H "Content-Type: application/json" \
            -H "x-api-key: ${{ secrets.AAC_API_KEY }}" \
            -d '{
              "image": "your-dockerhub-user/my-automation:latest",
              "folder": "tests",
              "baseUrl": "${{ secrets.TARGET_URL }}"
            }'

Step 6: Monitor & Review Results​

  1. Live Dashboard - Watch tests execute in real-time
  2. WebSocket Logs - See console output streaming live
  3. AI Analysis - When tests fail, AI analyzes root cause automatically
  4. Reports - Access HTML and Allure reports at: 
    https://api.agnox.dev/reports/{organizationId}/{taskId}/

Environment Variables Reference​

Your container receives these environment variables:

VariableDescription
BASE_URLTarget application URL (from your config or platform default)
TASK_IDUnique execution identifier
CIAlways true in platform execution
FRAMEWORK_AGNOSTICAlways true

Troubleshooting​

Container Fails to Start​

  1. Verify entrypoint.sh exists at /app/entrypoint.sh
  2. Check file has executable permissions (chmod +x)
  3. Ensure Unix line endings (not Windows CRLF)

Tests Not Found​

  1. Verify folder path matches your project structure
  2. Check that test files are included in Docker image
  3. Review logs for path-related errors

Reports Not Visible​

  1. Reports must be written to /app/<report-folder>
  2. Wait for execution to complete (status: PASSED or FAILED)
  3. Check that report generation step succeeded in logs

Next Steps​