zTester API Documentation

curl https://ztester.zavecoder.com/api/v1/projects \
  -H "Authorization: Bearer zt_your_api_key_here"

# Option 1: With environment (resolves URL + auth automatically)
curl -X POST ".../discover-tests" -d '{"source": "git", "environmentId": "env-uuid"}'

# Option 2: With explicit URL + auth
curl -X POST ".../discover-tests" -d '{
  "source": "git",
  "appUrl": "https://your-app.com",
  "auth": {"type": "email_password", "credentials": {"email": "...", "password": "..."}}
}'

# Option 3: With ActionExplorer for deep workflow tests
curl -X POST ".../discover-tests" -d '{
  "source": "git",
  "environmentId": "env-uuid",
  "actionExplorer": {"enabled": true}
}'

# Git-only mode (no DOM crawl) — omit appUrl and environmentId
curl -X POST ".../discover-tests" -d '{"source": "git"}'

# Configure safety endpoints on your environment
curl -X PATCH ".../environments?id=env-uuid" \
  -H "Authorization: Bearer zt_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "testSnapshotUrl": "https://your-api.com/test/snapshot",
    "testRestoreUrl": "https://your-api.com/test/restore"
  }'

# Your snapshot endpoint should:
# POST /test/snapshot → return { "snapshotId": "snap-123" }
# POST /test/restore  → accept { "snapshotId": "snap-123" }
# POST /test/reset    → reset to known state (simpler alternative)

<script src="https://ztester.zavecoder.com/sdk/ztester.js"></script>
<script>
  const zt = new ZTester.ZTester({ apiKey: 'zt_your_key' });

  // Run all project tests with live streaming
  zt.runProjectStream('your-project-id', {
    onTestStart: ({ testCaseName, index, total }) => {
      console.log(`[${index + 1}/${total}] Running: ${testCaseName}`);
    },
    onStepComplete: ({ stepIndex, status }) => {
      console.log(`  Step ${stepIndex + 1}: ${status}`);
    },
    onTestComplete: ({ testCaseId, status }) => {
      console.log(`  Result: ${status}`);
    },
  }).then(results => {
    const passed = results.filter(r => r.status === 'passed').length;
    console.log(`Done: ${passed}/${results.length} passed`);
  });
</script>

import { ZTester } from '@ztester/sdk';

const zt = new ZTester({ apiKey: process.env.ZTESTER_KEY });

// Single test with streaming
const result = await zt.runTestStream('test-uuid', {
  environmentId: 'env-uuid',      // optional — uses project default
  onStepStart: ({ description }) => updateUI(`Running: ${description}`),
  onStepComplete: ({ status }) => updateUI(`Step ${status}`),
  onHealing: ({ originalSelector, healedSelector }) =>
    updateUI(`Self-healed: ${originalSelector} → ${healedSelector}`),
});
console.log(`Test ${result.status} in ${result.durationMs}ms`);

// Discovery with polling
const disc = await zt.discoverTests('project-uuid', { source: 'git' });
const discovery = await zt.pollDiscovery('project-uuid', disc.discoveryId, {
  interval: 3000,
  onProgress: (d) => updateUI(`${d.progress?.testsGenerated} tests found...`),
});

// Submit feedback (selector fix + action fix)
await zt.submitFeedback('test-run-id', [
  {
    testCaseId: 'test-uuid-1',
    verdict: 'selector_fix',
    suggestedFix: {
      stepNumber: 2,
      currentSelector: 'button:nth-of-type(2)',
      suggestedSelector: "button:has-text('Submit')",
    },
  },
  {
    testCaseId: 'test-uuid-2',
    verdict: 'action_fix',
    suggestedFix: {
      stepNumber: 4,
      newAction: 'select',
      newValue: '{{first-option}}',
    },
    notes: 'Field is a <select> dropdown, not a text input',
  },
]);

<!-- Add this anywhere in your admin portal -->
<div id="ztester-widget"></div>
<script src="https://ztester.zavecoder.com/sdk/embed.js"></script>
<script>
  ZTesterEmbed.ZTesterEmbed.init({
    container: '#ztester-widget',
    apiKey: 'zt_your_api_key',
    projectId: 'your-project-id',
    theme: 'dark',                                        // 'dark' or 'light'
    features: ['run', 'discover', 'feedback', 'history'], // which tabs to show
    height: '700px',
    onReady: () => console.log('Widget loaded'),
    onTestComplete: (result) => {
      console.log('Test finished:', result.testCaseName, result.status);
    },
  });
</script>

Test Run (batch)
    │
    ├── All passed → done
    │
    └── Some failed
          │
          ▼
    AI Triage Agent
          │
          ├── Classify failure type (selector? timing? logic?)
          │
          ├── Generate fix (new selector, retry hint, etc.)
          │
          └── POST /test-runs/feedback
                │
                ├── verdict: "selector_fix" → auto-applies fix + re-runs
                ├── verdict: "action_fix"   → changes step action type (fill → select)
                ├── verdict: "flaky"        → increments flaky count, auto-retried next run
                ├── verdict: "false_positive"→ lowers confidence score
                └── verdict: "correct"      → boosts confidence score

import OpenAI from 'openai';

const openai = new OpenAI();

async function triageFailedTest(testRun: any, testCase: any) {
  // Find the failed step
  const failedStep = testRun.stepResults?.find(
    (s: any) => s.status === 'failed'
  );
  if (!failedStep) return null;

  // Check if it's a selector issue (timeout, not found)
  const isSelector = failedStep.error?.includes('Timeout') ||
    failedStep.error?.includes('not found') ||
    failedStep.error?.includes('waiting for selector');

  if (!isSelector) return null;

  // Ask LLM to classify and suggest fix
  const response = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{
      role: 'system',
      content: `You are a Playwright selector expert. Given a failed selector
and the page context, suggest a working CSS selector.
Return JSON: { "selector": "...", "confidence": 0.0-1.0, "reason": "..." }`
    }, {
      role: 'user',
      content: `Failed selector: ${failedStep.target}
Error: ${failedStep.error}
Step action: ${failedStep.type} (step #${failedStep.stepNumber})
Page URL: ${testRun.lastUrl || 'unknown'}
Test name: ${testCase.name}`
    }],
    response_format: { type: 'json_object' },
  });

  const fix = JSON.parse(response.choices[0].message.content || '{}');
  if (!fix.selector || fix.confidence < 0.6) return null;

  // Submit feedback with selector fix
  await fetch('https://ztester.zavecoder.com/api/v1/test-runs/feedback', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer zt_your_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      testRunId: testRun.id,
      testCaseId: testCase.id,
      verdict: 'selector_fix',
      feedbackType: 'selector',
      suggestedFix: {
        stepNumber: failedStep.stepNumber,
        currentSelector: failedStep.target,
        suggestedSelector: fix.selector,
      },
      notes: fix.reason,
    }),
  });

  // The API auto-applies the fix and triggers a verification re-run
  return fix;
}

async function detectFlakyTests(projectId: string, apiKey: string) {
  const BASE = 'https://ztester.zavecoder.com/api/v1';
  const headers = {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  };

  // Get recent test runs for the project
  const runsRes = await fetch(
    `${BASE}/test-runs?projectId=${projectId}&limit=100`,
    { headers }
  );
  const { results } = await runsRes.json();

  // Group by test case, check for pass/fail alternation
  const byTestCase = new Map<string, string[]>();
  for (const run of results) {
    const existing = byTestCase.get(run.testCaseId) || [];
    existing.push(run.status);
    byTestCase.set(run.testCaseId, existing);
  }

  const flakyFeedback = [];
  for (const [testCaseId, statuses] of byTestCase) {
    if (statuses.length < 3) continue;

    // Count alternations (pass→fail or fail→pass)
    let alternations = 0;
    for (let i = 1; i < statuses.length; i++) {
      if (statuses[i] !== statuses[i - 1]) alternations++;
    }

    const flakyScore = alternations / (statuses.length - 1);
    if (flakyScore > 0.4) {
      // More than 40% alternation = likely flaky
      flakyFeedback.push({
        testCaseId,
        verdict: 'flaky',
        notes: `Flaky score: ${(flakyScore * 100).toFixed(0)}% (${alternations} alternations in ${statuses.length} runs)`,
      });
    }
  }

  if (flakyFeedback.length > 0) {
    // Bulk submit flaky feedback
    const latestRunId = results[0]?.id;
    await fetch(`${BASE}/test-runs/feedback`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        testRunId: latestRunId,
        results: flakyFeedback,
      }),
    });
    console.log(`Marked ${flakyFeedback.length} tests as flaky`);
  }
}

async function analyzeWithVision(
  testRun: any,
  testCase: any,
  screenshot: Buffer, // from step_results[].screenshot
  domSnapshot: string // from step_results[].html
) {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{
      role: 'system',
      content: `Analyze this test failure. The test expected certain behavior but
the page shows something different. Classify as:
- "false_positive": App works correctly, test expectation is wrong
- "selector_fix": Element exists but with different selector
- "flaky": Looks like a timing/loading issue
- "correct": App genuinely has a bug

Return JSON: { "verdict": "...", "reason": "...", "suggestedSelector?": "..." }`
    }, {
      role: 'user',
      content: [
        {
          type: 'text',
          text: `Test: ${testCase.name}
Failed step: ${testRun.stepResults?.find((s: any) => s.status === 'failed')?.description}
Error: ${testRun.error}
DOM snippet (around failed element): ${domSnapshot.substring(0, 2000)}`
        },
        {
          type: 'image_url',
          image_url: {
            url: `data:image/png;base64,${screenshot.toString('base64')}`
          }
        }
      ]
    }],
    response_format: { type: 'json_object' },
  });

  const analysis = JSON.parse(
    response.choices[0].message.content || '{}'
  );

  // Submit the AI's verdict
  await fetch('https://ztester.zavecoder.com/api/v1/test-runs/feedback', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer zt_your_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      testRunId: testRun.id,
      testCaseId: testCase.id,
      verdict: analysis.verdict,
      feedbackType: 'assertion',
      notes: `[AI] ${analysis.reason}`,
      ...(analysis.suggestedSelector && {
        suggestedFix: {
          stepNumber: testRun.stepResults?.findIndex(
            (s: any) => s.status === 'failed'
          ) + 1,
          suggestedSelector: analysis.suggestedSelector,
        },
      }),
    }),
  });

  return analysis;
}

name: E2E Tests with AI Triage
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run zTester E2E Tests
        id: tests
        run: |
          RESULT=$(curl -s -X POST https://ztester.zavecoder.com/api/v1/test-runs \
            -H "Authorization: Bearer ${{ secrets.ZTESTER_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"projectId": "${{ secrets.ZTESTER_PROJECT_ID }}"}')

          echo "result=$RESULT" >> $GITHUB_OUTPUT
          STATUS=$(echo $RESULT | jq -r '.status')
          echo "status=$STATUS" >> $GITHUB_OUTPUT

      - name: AI Triage Failed Tests
        if: steps.tests.outputs.status != 'passed'
        run: |
          node scripts/ai-triage.js \
            --api-key "${{ secrets.ZTESTER_API_KEY }}" \
            --openai-key "${{ secrets.OPENAI_API_KEY }}" \
            --result '${{ steps.tests.outputs.result }}'

      - name: Re-run After Fixes Applied
        if: steps.tests.outputs.status != 'passed'
        run: |
          # Wait for selector fixes to be applied
          sleep 10

          # Re-run only the failed tests
          FAILED=$(echo '${{ steps.tests.outputs.result }}' | \
            jq -r '[.results[] | select(.status != "passed") | .testCaseId] | join(",")')

          for TEST_ID in $(echo $FAILED | tr ',' ' '); do
            curl -s -X POST https://ztester.zavecoder.com/api/v1/test-runs \
              -H "Authorization: Bearer ${{ secrets.ZTESTER_API_KEY }}" \
              -H "Content-Type: application/json" \
              -d "{\"testCaseId\": \"$TEST_ID\"}"
          done

function classifyFailure(stepResult: any): string {
  const error = stepResult.error || '';

  // 1. Timeout / element not found → likely selector issue
  if (error.includes('Timeout') ||
      error.includes('waiting for selector') ||
      error.includes('not found')) {
    return 'selector_fix';
  }

  // 2. Wrong action type (fill on select, selectOption on input)
  if (error.includes('selectOption') ||
      error.includes('Not a SELECT element') ||
      error.includes('Element is not a <select>') ||
      error.includes('is not an <input>')) {
    return 'action_fix';
  }

  // 3. Navigation error → might be flaky (network)
  if (error.includes('net::ERR_') ||
      error.includes('Navigation timeout') ||
      error.includes('frame was detached')) {
    return 'flaky';
  }

  // 4. Assertion failure → needs deeper analysis (use LLM)
  if (error.includes('expect') ||
      error.includes('assertion') ||
      error.includes('toBeVisible') ||
      error.includes('toHaveText')) {
    return 'needs_llm_analysis';
  }

  // 5. Permission / auth errors → likely environment issue
  if (error.includes('403') ||
      error.includes('401') ||
      error.includes('Unauthorized')) {
    return 'not_applicable';
  }

  // 6. Default: send to LLM for classification
  return 'needs_llm_analysis';
}