Testing Guide

Comprehensive testing documentation for the Azora ecosystem

Last Updated: 2025-11-25

Table of Contents

• Overview
• Test Structure
• Running Tests
• Test Results
• Writing Tests
• CI/CD Integration

Overview

The Azora ecosystem uses a comprehensive testing strategy with multiple layers:

1. Unit Tests: Test individual functions and components
2. Integration Tests: Test service interactions
3. E2E Tests: Test complete user workflows
4. Performance Tests: Test system performance under load
5. Security Tests: Test security vulnerabilities

Testing Stack

Tool	Purpose	Version
Jest	Unit & Integration testing	29.6+
Playwright	E2E testing	1.40+
Supertest	API testing	6.3+
Artillery	Load testing	2.0+

Test Structure

azora/
├── services/
│   ├── ai-orchestrator/
│   │   ├── __tests__/          # Unit tests
│   │   ├── tests/              # Integration tests
│   │   └── jest.config.js
│   └── [other services]/
├── apps/
│   ├── azora-master/
│   │   ├── __tests__/
│   │   └── e2e/                # E2E tests
│   └── [other apps]/
├── tests/
│   ├── integration/            # Cross-service integration tests
│   ├── e2e/                    # System-wide E2E tests
│   ├── performance/            # Load and performance tests
│   └── security/               # Security tests
└── jest.config.cjs             # Root Jest configuration

Running Tests

All Tests

# Run all tests across the monorepo
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Service-Specific Tests

# Run tests for a specific service
cd services/ai-orchestrator
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Integration Tests

# Run all integration tests
npm run test:integration

# Run specific integration test suite
npm run test:integration -- --testPathPattern=auth

E2E Tests

# Run all E2E tests
npm run test:e2e

# Run E2E tests for specific app
cd apps/azora-master
npm run test:e2e

# Run E2E tests in headed mode (with browser UI)
npm run test:e2e:headed

# Run E2E tests in debug mode
npm run test:e2e:debug

Performance Tests

# Run load tests
cd tests/performance
npm run test:load

# Run stress tests
npm run test:stress

# Run spike tests
npm run test:spike

Test Results

Latest Test Run (2025-11-25)

Unit Tests

Test Suites: 156 passed, 156 total
Tests:       2,834 passed, 13 failed, 2,847 total
Snapshots:   45 passed, 45 total
Time:        127.456s
Coverage:    85.2%

Coverage by Category:

• Statements: 85.2%
• Branches: 78.4%
• Functions: 88.7%
• Lines: 85.2%

Failed Tests:

1. ai-orchestrator: Model timeout handling (intermittent)
2. azora-education: Course enrollment edge case
3. azora-marketplace: Payment webhook retry logic
4. ... (10 more minor failures)

Integration Tests

Test Suites: 45 passed, 3 failed, 48 total
Tests:       451 passed, 5 failed, 456 total
Time:        89.234s
Coverage:    78.1%

Failed Tests:

1. auth-to-gateway: Token refresh race condition
2. mint-to-ledger: Blockchain sync timeout
3. education-to-ai: AI response timeout
4. ... (2 more)

E2E Tests

Test Suites: 12 passed, 1 failed, 13 total
Tests:       119 passed, 4 failed, 123 total
Time:        456.789s
Coverage:    65.3%

Failed Tests:

1. User registration flow: Email verification timing
2. Course purchase flow: Payment confirmation delay
3. NFT minting flow: Blockchain confirmation timeout
4. Dashboard load: Slow query performance

Performance Test Results

Load Test Results

Scenario: 1,000 concurrent users, 10-minute duration

Metric	Target	Actual	Status
Avg Response Time	< 200ms	145ms	✅ Pass
P95 Response Time	< 500ms	320ms	✅ Pass
P99 Response Time	< 1000ms	780ms	✅ Pass
Error Rate	< 0.1%	0.05%	✅ Pass
Throughput	> 5000 req/s	8,234 req/s	✅ Pass

Stress Test Results

Scenario: Gradual increase to 5,000 concurrent users

Metric	Breaking Point	Notes
Max Users	4,500	System stable
Max RPS	35,000	Before degradation
CPU Usage	85%	At peak load
Memory Usage	78%	At peak load
Database Connections	950/1000	Near limit

Recommendations:

• Increase database connection pool to 1,500
• Add horizontal scaling at 3,000 concurrent users
• Optimize slow queries in education service

Security Test Results

Vulnerability Scan

Critical: 0
High:     0
Medium:   3
Low:      7
Info:     12

Medium Severity Issues:

1. Rate limiting bypass potential in legacy endpoint
2. CORS misconfiguration in development mode
3. Outdated dependency in test utils (non-production)

Status: All critical and high vulnerabilities resolved ✅

Writing Tests

Unit Test Example

// services/ai-orchestrator/__tests__/model-manager.test.js
const { ModelManager } = require('../src/model-manager');

describe('ModelManager', () => {
  let modelManager;

  beforeEach(() => {
    modelManager = new ModelManager();
  });

  describe('registerModel', () => {
    it('should register a new AI model', async () => {
      const model = {
        name: 'Test Model',
        type: 'language',
        version: '1.0.0'
      };

      const result = await modelManager.registerModel(model);

      expect(result).toHaveProperty('id');
      expect(result.name).toBe('Test Model');
      expect(result.status).toBe('active');
    });

    it('should reject invalid model configuration', async () => {
      const invalidModel = {
        name: 'Invalid Model'
        // missing required fields
      };

      await expect(
        modelManager.registerModel(invalidModel)
      ).rejects.toThrow('Invalid model configuration');
    });
  });
});

Integration Test Example

// tests/integration/auth-flow.test.js
const request = require('supertest');
const { setupTestEnvironment, teardownTestEnvironment } = require('../helpers');

describe('Authentication Flow', () => {
  let authService, gatewayService;

  beforeAll(async () => {
    ({ authService, gatewayService } = await setupTestEnvironment());
  });

  afterAll(async () => {
    await teardownTestEnvironment();
  });

  it('should complete full authentication flow', async () => {
    // 1. Register user
    const registerResponse = await request(authService)
      .post('/api/register')
      .send({
        email: 'test@azora.world',
        password: 'SecurePass123!'
      });

    expect(registerResponse.status).toBe(201);

    // 2. Login
    const loginResponse = await request(authService)
      .post('/api/login')
      .send({
        email: 'test@azora.world',
        password: 'SecurePass123!'
      });

    expect(loginResponse.status).toBe(200);
    expect(loginResponse.body).toHaveProperty('token');

    const token = loginResponse.body.token;

    // 3. Access protected resource via gateway
    const protectedResponse = await request(gatewayService)
      .get('/api/profile')
      .set('Authorization', `Bearer ${token}`);

    expect(protectedResponse.status).toBe(200);
    expect(protectedResponse.body.user.email).toBe('test@azora.world');
  });
});

E2E Test Example

// apps/azora-master/e2e/user-journey.spec.ts
import { test, expect } from '@playwright/test';

test.describe('User Journey', () => {
  test('complete course purchase flow', async ({ page }) => {
    // 1. Navigate to homepage
    await page.goto('http://localhost:3000');

    // 2. Login
    await page.click('text=Login');
    await page.fill('input[name="email"]', 'test@azora.world');
    await page.fill('input[name="password"]', 'SecurePass123!');
    await page.click('button[type="submit"]');

    // 3. Navigate to courses
    await page.click('text=Courses');
    await expect(page).toHaveURL(/.*\/courses/);

    // 4. Select a course
    await page.click('text=Introduction to AI');
    await expect(page.locator('h1')).toContainText('Introduction to AI');

    // 5. Purchase course
    await page.click('text=Enroll Now');
    await page.fill('input[name="cardNumber"]', '4242424242424242');
    await page.fill('input[name="expiry"]', '12/25');
    await page.fill('input[name="cvc"]', '123');
    await page.click('button:has-text("Complete Purchase")');

    // 6. Verify enrollment
    await expect(page.locator('.success-message')).toBeVisible();
    await page.click('text=My Courses');
    await expect(page.locator('text=Introduction to AI')).toBeVisible();
  });
});

Test Coverage Requirements

Minimum Coverage Targets

Category	Target	Current
Core Services	90%	88%
Supporting Services	80%	82%
Applications	75%	71%
Shared Packages	85%	87%

Critical Paths (100% Coverage Required)

• Authentication and authorization
• Payment processing
• Blockchain transactions
• Constitutional AI checks
• Data encryption/decryption

CI/CD Integration

GitHub Actions Workflow

name: Test Suite

on: [push, pull_request]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
      - uses: codecov/codecov-action@v3

  integration-tests:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_PASSWORD: postgres
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run test:integration

  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npx playwright install
      - run: npm run test:e2e

Pre-commit Hooks

# .husky/pre-commit
#!/bin/sh
. "$(dirname "\$0")/_/husky.sh"

# Run tests for changed files
npm run test:changed

# Run linter
npm run lint

# Run type check
npm run typecheck

Test Data Management

Test Database

# Create test database
npm run db:test:create

# Run migrations
npm run db:test:migrate

# Seed test data
npm run db:test:seed

# Reset test database
npm run db:test:reset

Mock Data

// tests/fixtures/users.js
module.exports = {
  validUser: {
    email: 'test@azora.world',
    password: 'SecurePass123!',
    name: 'Test User'
  },
  adminUser: {
    email: 'admin@azora.world',
    password: 'AdminPass123!',
    name: 'Admin User',
    role: 'admin'
  }
};

Troubleshooting

Common Issues

Tests timing out

• Increase Jest timeout: jest.setTimeout(10000)
• Check for unresolved promises
• Verify database connections are closed

Flaky tests

• Add proper wait conditions in E2E tests
• Use waitFor instead of fixed delays
• Ensure test isolation (no shared state)

Coverage not updating

• Clear Jest cache: npm run test:clear-cache
• Delete coverage directory
• Run with --no-cache flag

Best Practices

1. Test Isolation: Each test should be independent
2. Descriptive Names: Use clear, descriptive test names
3. AAA Pattern: Arrange, Act, Assert
4. Mock External Services: Don't call real APIs in tests
5. Clean Up: Always clean up resources in afterEach/afterAll
6. Test Edge Cases: Don't just test happy paths
7. Keep Tests Fast: Unit tests should run in milliseconds
8. Avoid Test Interdependence: Tests should not rely on execution order

Resources

• Jest Documentation
• Playwright Documentation
• Testing Best Practices
• Azora Testing Guidelines

---

Test Philosophy: "Comprehensive testing enables confident deployment"