QAagentic JavaScript/TypeScript SDK

🚀 Installation

npm install qagentic-reporter
# or
yarn add qagentic-reporter
# or
pnpm add qagentic-reporter

⚡ Quick Start

Cypress

// cypress.config.ts
import { defineConfig } from 'cypress';
import { setupQAgentic } from 'qagentic-reporter/cypress/simple-setup';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      setupQAgentic(on, config);  // That's it!
      return config;
    },
  },
});

Playwright

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { qagenticReporter } from 'qagentic-reporter/playwright';

export default defineConfig({
  reporter: [
    ['html'],
    qagenticReporter({
      projectName: 'my-project',
      apiUrl: 'http://localhost:8000',
    }),
  ],
});

Jest

// jest.config.js
module.exports = {
  reporters: [
    'default',
    ['qagentic-reporter/jest', {
      projectName: 'my-project',
      apiUrl: 'http://localhost:8000',
    }],
  ],
};

📝 Usage Examples

Steps in Cypress

// cypress/e2e/login.cy.js
import { step, feature, story, severity } from 'qagentic-reporter/cypress';

describe('User Authentication', () => {
  it('should login successfully', () => {
    step('Navigate to login page', () => {
      cy.visit('/login');
    });

    step('Enter credentials', () => {
      cy.get('#email').type('[email protected]');
      cy.get('#password').type('password123');
    });

    step('Submit and verify', () => {
      cy.get('button[type="submit"]').click();
      cy.url().should('include', '/dashboard');
    });
  });
});

Steps in Playwright

// tests/login.spec.ts
import { test, expect } from '@playwright/test';
import { step } from 'qagentic-reporter/playwright';

test('should login successfully', async ({ page }) => {
  await step('Navigate to login page', async () => {
    await page.goto('/login');
  });

  await step('Enter credentials', async () => {
    await page.fill('#email', '[email protected]');
    await page.fill('#password', 'password123');
  });

  await step('Submit and verify', async () => {
    await page.click('button[type="submit"]');
    await expect(page).toHaveURL(/dashboard/);
  });
});

Attachments

import { attach, attachScreenshot, attachJson } from 'qagentic-reporter';

// Attach screenshot
attachScreenshot('path/to/screenshot.png', 'Login Page');

// Attach JSON data
attachJson({ status: 'success', userId: 123 }, 'API Response');

// Attach text
attachText('Log output here...', 'Console Logs');

⚙️ Configuration

Environment Variables

QAGENTIC_PROJECT_NAME=my-project
QAGENTIC_API_URL=http://localhost:8000
QAGENTIC_API_KEY=your-api-key
QAGENTIC_OUTPUT_DIR=./qagentic-results
QAGENTIC_AI_ANALYSIS=true

Configuration File

# qagentic.yaml
project:
  name: my-project
  environment: staging

reporting:
  api:
    enabled: true
    url: http://localhost:8000
    key: ${QAGENTIC_API_KEY}
  local:
    enabled: true
    output_dir: ./qagentic-results
    formats:
      - json
      - html
      - junit

features:
  ai_analysis: true
  screenshots: on_failure

🔌 API Schema

The SDK automatically sends a single POST /ingest/ request at the end of each test run. No manual calls needed. For debugging or custom integrations:

POST /ingest/
Content-Type: application/json
X-API-Key: <your-api-key>

{
  "run_name": "cypress_20260325T120000",
  "framework": "cypress",               // cypress | playwright | jest
  "branch": "main",                     // from CI env or GITHUB_REF_NAME
  "commit_hash": "abc123",              // from CI env or GITHUB_SHA
  "environment": "staging",
  "test_cases": [
    {
      "name": "Auth > should login",
      "status": "passed",               // passed | failed | skipped
      "duration_ms": 1234,
      "error_message": null,
      "error_type": null,
      "error_stacktrace": null
    }
  ]
}

Response: 202 Accepted with { "run_id": "uuid" }

🔌 CI/CD Integration

GitHub Actions

- name: Run Cypress Tests
  run: npx cypress run
  env:
    QAGENTIC_API_URL: ${{ secrets.QAGENTIC_API_URL }}
    QAGENTIC_API_KEY: ${{ secrets.QAGENTIC_API_KEY }}

- name: Upload Results
  uses: actions/upload-artifact@v3
  if: always()
  with:
    name: qagentic-results
    path: qagentic-results/

GitLab CI

test:
  script:
    - npx cypress run
  artifacts:
    when: always
    paths:
      - qagentic-results/
    reports:
      junit: qagentic-results/junit.xml

📊 Output Formats

• JSON Report - Machine-readable results
• JUnit XML - CI/CD compatible
• HTML Report - Interactive dashboard

🧠 AI Features

When connected to QAagentic server:

• Automatic Root Cause Analysis
• Failure Clustering
• Flaky Test Detection
• Smart Recommendations

📚 API Reference

Core Functions

| Function | Description | |----------|-------------| | step(name, fn) | Create a test step | | attach(data, name) | Attach data to test | | attachScreenshot(path) | Attach screenshot | | attachJson(data) | Attach JSON data |

Decorators/Labels

| Function | Description | |----------|-------------| | feature(name) | Group by feature | | story(name) | Group by user story | | severity(level) | Set severity level | | tag(...tags) | Add tags |

🔄 Migration Guide

Upgrading from v0.1.42 and earlier

What changed in v0.1.43:

• APIReporter (the old 3-call protocol) has been removed
• All test results are now sent via a single POST /ingest/ call at the end of the run
• Jest reporter now correctly sends results to the backend (was broken in previous versions)

What you need to do:

For most users — nothing. If you used the standard setup (setupQAgentic, QAgenticPlaywrightReporter, or QAgenticJestReporter), the transition is automatic:

npm install [email protected]

If you explicitly used APIReporter (advanced usage), remove those calls:

// BEFORE — remove these
import { APIReporter } from 'qagentic-reporter';
const reporter = new APIReporter();
await reporter.startRun(run);
// ...
await reporter.endRun(run);

// AFTER — use sendIngestPayload directly if needed
import { sendIngestPayload } from 'qagentic-reporter/core/ingest-client';
await sendIngestPayload(run, 'cypress');

Why the old approach failed: The /api/v1/runs/* endpoints never existed in qagentic-core — they were part of an old API Gateway that was removed in the platform consolidation (Epic 1). The /ingest/ endpoint is the only supported ingestion path.

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.