UATT: Universal Automated Testing Tool

AI-Powered Testing Framework for Modern Web Applications

📖 Overview

UATT is a next-generation testing framework that combines AI-driven automation, visual regression, performance auditing, and API testing into a single, powerful CLI tool. Stop writing brittle tests—let AI handle the complexity.

✨ What Makes UATT Different?

| Traditional Testing | UATT | |---------------------|------| | Manual selector maintenance | 🤖 Self-healing AI locators | | Fragile, flaky tests | 🔧 Automatic resilience & retry logic | | Separate tools for each test type | 🎯 Unified framework (E2E + Visual + Performance + API) | | Hours writing tests | ⚡ Generate tests from natural language | | Static reports | 📊 Live, interactive dashboard |

🚀 Quick Start

Installation

# Install UATT
npm install -D uatt-restk

# Install Playwright browsers
npx playwright install chromium

# Initialize UATT in your project
npx uatt init

Your First Test

# Run tests
npx uatt test

# View results in dashboard
npx uatt dashboard

# Generate a test from plain English
npx uatt generate "Test login flow with valid credentials"

That's it! UATT is ready to use.

🎯 Key Features

🤖 AI-Driven Testing

Natural Language Test Generation

npx uatt generate "User adds product to cart and completes checkout"

UATT generates a complete, executable Playwright test from your description.

Self-Healing Locators

import { NavigationAgent } from 'uatt-restk/agents';

test('AI navigation', async ({ page }) => {
  const agent = new NavigationAgent(page);

  // AI autonomously finds and clicks elements
  await agent.achieveGoal(
    'https://example.com',
    'Navigate to pricing page and find enterprise plan'
  );
});

No more broken selectors when the DOM changes!

📸 Visual Regression Testing

import { compareScreenshots } from 'uatt-restk/visual';

test('visual regression', async ({ page }) => {
  await page.goto('/');

  const screenshot = await page.screenshot();
  const diff = await compareScreenshots(
    screenshot,
    'baselines/homepage.png',
    'reports/diffs/homepage-diff.png'
  );

  expect(diff.mismatchPercentage).toBeLessThan(1);
});

Automatic baseline management and pixel-perfect diff visualization.

⚡ Performance Auditing

import { runLighthouse } from 'uatt-restk/audits';

test('performance check', async ({ page }) => {
  const results = await runLighthouse(page, 'https://example.com');

  expect(results.scores.performance).toBeGreaterThan(0.9);
  expect(results.scores.accessibility).toBeGreaterThan(0.95);
});

Built-in Lighthouse integration for performance, accessibility, SEO, and PWA audits.

🔌 API Fuzzing

import { runApiFuzzing } from 'uatt-restk/core';

test('API security', async () => {
  const results = await runApiFuzzing({
    schemaUrl: 'https://api.example.com/openapi.json',
    baseUrl: 'https://api.example.com'
  });

  expect(results.success).toBe(true);
});

Automatic API testing with Schemathesis integration.

📚 CLI Commands

uatt init

Initialize UATT in your project with different templates:

# Basic functional testing
npx uatt init --template basic

# AI-driven testing
npx uatt init --template ai

# Visual regression testing
npx uatt init --template visual

# Full stack (all features)
npx uatt init --template full

Options:

• --template <type> - Template type: basic, ai, visual, full (default: basic)
• --force - Overwrite existing files

uatt test

Run your tests:

# Run all tests
npx uatt test

# Run specific suite
npx uatt test smoke

# Run in headed mode (see browser)
npx uatt test --headed

# Run in debug mode
npx uatt test --debug

# Run in UI mode
npx uatt test --ui

# Run specific project
npx uatt test --project chromium

Options:

• --headed - Run tests in headed mode
• --debug - Run tests in debug mode with Playwright Inspector
• --ui - Run tests in Playwright UI mode
• --project <name> - Run specific project

uatt generate

Generate tests from natural language:

npx uatt generate "Test user registration flow"

# Custom output path
npx uatt generate "Test checkout" --output tests/checkout.spec.ts

# Specify target URL
npx uatt generate "Test homepage" --url https://example.com

Options:

• --output <path> - Output file path (default: tests/generated.spec.ts)
• --url <url> - Target URL to test

uatt dashboard

Launch the interactive test results dashboard:

# Start dashboard (auto-opens browser)
npx uatt dashboard

# Custom port
npx uatt dashboard --port 9000

# Don't auto-open browser
npx uatt dashboard --no-open

Options:

• --port <port> - Port number (default: 3005)
• --open - Automatically open browser (default: true)

uatt doctor

Check your UATT configuration and environment:

# Run health check
npx uatt doctor

# Auto-fix issues
npx uatt doctor --fix

Checks:

• Node.js version
• Playwright installation
• Configuration files
• Test directories
• Environment variables
• Browser binaries

uatt report

Open the latest test report:

# Open HTML report
npx uatt report

# Open JSON report
npx uatt report --type json

# Open dashboard
npx uatt report --type dashboard

Options:

• --type <type> - Report type: html, json, dashboard (default: html)

uatt update-snapshots

Update visual regression baselines:

# Update all snapshots
npx uatt update-snapshots

# Update specific test
npx uatt update-snapshots --test "homepage visual"

Options:

• --test <pattern> - Update specific test pattern

🔧 Configuration

UATT uses a uatt.config.ts file for configuration:

import { defineConfig } from 'uatt-restk';

export default defineConfig({
  projectName: 'My App Tests',

  // Test discovery
  testMatch: ['**/*.spec.{ts,js}'],

  // AI Features
  ai: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4o',
    features: {
      selfHealing: true,
      testGeneration: true,
      smartLocators: true
    }
  },

  // Visual Testing
  visual: {
    engine: 'pixelmatch',
    threshold: 0.1,
    baselineDir: './baselines',
    diffDir: './reports/diffs'
  },

  // Performance
  performance: {
    lighthouse: {
      enabled: true,
      thresholds: {
        performance: 80,
        accessibility: 90,
        bestPractices: 80,
        seo: 80
      }
    },
    webVitals: true
  },

  // Reporting
  reporters: [
    'html',
    'json',
    ['uatt-dashboard', { port: 3005 }]
  ]
});

📁 Project Structure

my-app/
├── tests/                      # Test files
│   ├── example.spec.ts
│   ├── visual.spec.ts
│   └── performance.spec.ts
├── baselines/                  # Visual regression baselines
├── reports/                    # Test reports and artifacts
│   ├── unified-report.json
│   ├── lighthouse.html
│   └── diffs/
├── playwright.config.ts        # Playwright configuration
├── uatt.config.ts             # UATT configuration
└── .env                        # Environment variables

🛠 Tech Stack

• Core: Node.js 18+, TypeScript 5.0, ESM
• E2E Engine: Playwright 1.59+
• Performance: Lighthouse 12.8+
• API Fuzzing: Schemathesis
• AI/LLM: OpenAI GPT-4o / Claude 3.5
• Visual: Pixelmatch, PNGjs
• CLI: Commander.js
• Dashboard: Express, EJS, TailwindCSS

🌟 Examples

Basic E2E Test

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

test('user can login', async ({ page }) => {
  await page.goto('/login');
  await page.fill('[name="email"]', '[email protected]');
  await page.fill('[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  await expect(page).toHaveURL('/dashboard');
});

AI-Powered Test

import { test } from '@playwright/test';
import { NavigationAgent } from 'uatt-restk/agents';

test('AI completes user journey', async ({ page }) => {
  const agent = new NavigationAgent(page);

  const result = await agent.achieveGoal(
    'https://example.com',
    'Search for "laptop", filter by price under $1000, and add to cart'
  );

  console.log('Steps taken:', result.steps);
  expect(result.success).toBe(true);
});

Visual + Performance Test

import { test, expect } from '@playwright/test';
import { compareScreenshots } from 'uatt-restk/visual';
import { runLighthouse } from 'uatt-restk/audits';

test('comprehensive homepage check', async ({ page }) => {
  await page.goto('/');

  // Visual regression
  const screenshot = await page.screenshot();
  const diff = await compareScreenshots(
    screenshot,
    'baselines/homepage.png',
    'reports/diffs/homepage-diff.png'
  );
  expect(diff.mismatchPercentage).toBeLessThan(1);

  // Performance audit
  const lighthouse = await runLighthouse(page, '/');
  expect(lighthouse.scores.performance).toBeGreaterThan(0.9);
  expect(lighthouse.scores.accessibility).toBeGreaterThan(0.95);
});

🚨 Troubleshooting

Tests are failing

# Run in debug mode
npx uatt test --debug

# Run in headed mode to see what's happening
npx uatt test --headed

# Check configuration
npx uatt doctor

AI features not working

1. Make sure you have set OPENAI_API_KEY in your .env file
2. Verify your API key: echo $OPENAI_API_KEY
3. Check your config: npx uatt doctor

Dashboard won't start

# Check if port is already in use
npx uatt dashboard --port 9000

# View reports directly
npx uatt report

Snapshots keep failing

# Update baselines
npx uatt update-snapshots

# Adjust threshold in uatt.config.ts
visual: {
  threshold: 0.5  # Higher = more tolerant
}

📖 Documentation

• Getting Started Guide
• API Reference
• Configuration
• Examples
• Architecture
• Implementation Strategy

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository
• npm Package
• Documentation
• Issue Tracker

Built with ❤️ by the UATT Team

Report Bug · Request Feature · Documentation