AngularUITest

Features

• ✅ One-Command Setup - Get started in minutes with ng add angular-uitest
• ⚡ Lightning Fast - Vitest for rapid unit testing feedback
• 🎭 Real Browser Testing - Playwright for E2E and component tests
• 📊 Beautiful Reports - Allure integration for all test types
• 🔧 Pre-Configured - Works out of the box with Angular
• 🛠️ Helper Library - Common testing utilities included
• 🔍 Debug Interface - Access Angular app state in tests
• 🚀 CI/CD Ready - GitHub Actions, GitLab CI, Azure DevOps support

Installation

Using Angular CLI (Recommended)

ng add angular-uitest

Using npm

npm install --save-dev angular-uitest
npx samaro-init

Install Playwright Browsers

npx playwright install chromium

Quick Start

After installation, you can immediately start testing:

# Run unit tests
npm run test

# Run E2E tests
npm run test:e2e

# Run component tests
npm run test:ct

# Generate and view reports
npm run allure:generate
npm run allure:open

Available Scripts

| Script | Description | |--------|-------------| | npm run test | Run unit tests with Vitest | | npm run test:run | Run unit tests once (CI mode) | | npm run test:ui | Run unit tests with UI | | npm run test:coverage | Run unit tests with coverage | | npm run test:e2e | Run E2E tests with Playwright | | npm run test:e2e:ui | Run E2E tests with Playwright UI | | npm run test:e2e:headed | Run E2E tests in headed mode | | npm run test:ct | Run component tests | | npm run allure:generate | Generate Allure reports | | npm run allure:open | Open Allure reports | | npm run allure:clean | Clean Allure results |

Writing Tests

Unit Tests

// src/app/services/user.service.spec.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { TestBed } from '@angular/core/testing';
import { UserService } from './user.service';

describe('UserService', () => {
  let service: UserService;

  beforeEach(() => {
    TestBed.configureTestingModule({});
    service = TestBed.inject(UserService);
  });

  it('should be created', () => {
    expect(service).toBeTruthy();
  });
});

E2E Tests

// e2e/auth.spec.ts
import { test, expect } from '@playwright/test';
import { generateUniqueUser, register } from 'angular-uitest/helpers';

test('user can register', async ({ page }) => {
  const user = generateUniqueUser();
  
  await register(page, user.username, user.email, user.password);
  
  await expect(page).toHaveURL('/');
});

Component Tests

// ct-tests/button.spec.ts
import { test, expect } from '@playwright/test';

test('button renders correctly', async ({ page }) => {
  await page.goto('/button-test');
  
  const button = page.locator('app-button');
  await expect(button).toBeVisible();
});

Test Helpers

Debug Interface

Access your Angular app's state during tests:

import { getToken, getAuthState, waitForAuthState } from 'angular-uitest/helpers';

test('user login', async ({ page }) => {
  await login(page, '[email protected]', 'password');
  
  // Wait for auth state
  await waitForAuthState(page, 'authenticated');
  
  // Get token
  const token = await getToken(page);
  expect(token).toBeTruthy();
});

Authentication

import { generateUniqueUser, register, login, logout } from 'angular-uitest/helpers';

const user = generateUniqueUser();
await register(page, user.username, user.email, user.password);
await logout(page);
await login(page, user.email, user.password);

API Helpers

Speed up tests by using APIs for setup:

import { registerUserViaAPI } from 'angular-uitest/helpers';

test('create article', async ({ page, request }) => {
  const { token } = await registerUserViaAPI(request, {
    username: 'testuser',
    email: '[email protected]',
    password: 'password123',
  });
  
  // Use token for authenticated requests
});

Configuration

Vitest Configuration

// vitest.config.ts
import { createVitestConfig, mergeConfig } from 'angular-uitest/config';

export default mergeConfig(
  createVitestConfig({
    testGlob: 'src/**/*.spec.ts',
  }),
  {
    test: {
      coverage: {
        exclude: ['**/legacy/**'],
      },
    },
  }
);

Playwright Configuration

// playwright.config.ts
import { createPlaywrightConfig } from 'angular-uitest/config';

export default createPlaywrightConfig({
  baseURL: 'http://localhost:4200',
  testDir: './e2e',
  webServerCommand: 'npm run start',
  webServerPort: 4200,
});

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | API_MODE | Use API for setup operations | true | | API_BASE | Base URL for API calls | http://localhost:4200/api | | DEBUG_INTERFACE_NAME | Name of debug interface | __app_debug__ | | CI | CI mode (auto-clean results) | false |

CI/CD Integration

GitHub Actions

name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx playwright install chromium
      - run: npm run test:run
      - run: npm run test:e2e
      - run: npm run allure:generate

Troubleshooting

Playwright browsers not installed

npx playwright install chromium

Tests fail with timeout

Increase timeout in configuration:

export default createPlaywrightConfig({
  webServer: {
    timeout: 180_000,
  },
});

Debug interface not available

Implement debug interface in your Angular app:

// app.component.ts
if (typeof window !== 'undefined') {
  window.__app_debug__ = {
    getToken: () => this.authService.getToken(),
    getAuthState: () => this.authService.getAuthState(),
    getCurrentUser: () => this.authService.getCurrentUser(),
  };
}

Documentation

• Complete Developer Documentation - Comprehensive guide for using the package
• Vitest Documentation
• Playwright Documentation
• Allure Documentation
• Angular Testing Guide

License

MIT © Samaro