Skip to content

TEST_DOCUMENTATION.md

Latest commit

 

History

History
402 lines (318 loc) · 8.66 KB

TEST_DOCUMENTATION.md

File metadata and controls

402 lines (318 loc) · 8.66 KB

Angular UI Testing Documentation

Overview

This document provides comprehensive information about the test suite for the Angular UI application, which has been updated to Angular 19.0.0.

Table of Contents

  1. Test Structure
  2. Running Tests
  3. Test Types
  4. Test Coverage
  5. Writing New Tests
  6. CI/CD Integration
  7. Troubleshooting

Test Structure

The test suite is organized into the following categories:

Unit Tests

Located in src/app/*.spec.ts

  • app.component.spec.ts: Main component unit tests
  • app.service.spec.ts: Service layer tests
  • form-validation.spec.ts: Form validation tests
  • captcha.service.spec.ts: Captcha functionality tests
  • performance.spec.ts: Performance benchmarking tests

Integration Tests

Located in src/app/*.integration.spec.ts

  • login.integration.spec.ts: Full login flow integration tests

E2E Tests

Located in e2e/src/*.e2e-spec.ts

  • login.e2e-spec.ts: End-to-end login tests

Running Tests

Run All Unit Tests

npm test

Run Tests in CI Mode (Headless)

npm run test:ci

Run Tests with Coverage

npm run test:coverage

Run E2E Tests

npm run e2e

Run Specific Test File

ng test --include='**/app.component.spec.ts'

Run Tests in Watch Mode

ng test --watch

Test Types

1. Component Unit Tests

Tests individual component behavior, methods, and properties.

Example:

it('should initialize with null captcha', () => {
  expect(component.captcha).toBeNull();
});

2. Form Validation Tests

Tests all form validation rules and error messages.

Coverage:

  • Empty field validation
  • Missing field validation
  • Valid input acceptance
  • Error message accuracy

3. Integration Tests

Tests complete workflows and interactions between components.

Coverage:

  • Full login flow
  • Captcha refresh during login
  • Error recovery flows
  • State consistency

4. Performance Tests

Benchmarks component performance and identifies bottlenecks.

Coverage:

  • Component initialization time
  • Form validation speed
  • Memory usage
  • Change detection performance
  • Rendering performance

5. E2E Tests

Tests user interactions from a browser perspective.

Coverage:

  • Page load behavior
  • Form interactions
  • Button clicks
  • Error display
  • Responsive design

Test Coverage

Coverage Goals

  • Statements: 80%
  • Branches: 75%
  • Functions: 80%
  • Lines: 80%

View Coverage Report

After running npm run test:coverage, open:

coverage/AngularUI/index.html

Current Test Count

  • Unit Tests: 100+ test cases
  • Integration Tests: 30+ test cases
  • E2E Tests: 40+ test cases
  • Performance Tests: 20+ test cases

Writing New Tests

Test File Naming Convention

  • Unit tests: *.spec.ts
  • Integration tests: *.integration.spec.ts
  • E2E tests: *.e2e-spec.ts

Basic Test Template

import { TestBed, ComponentFixture } from '@angular/core/testing';
import { YourComponent } from './your-component';

describe('YourComponent', () => {
  let component: YourComponent;
  let fixture: ComponentFixture<YourComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [YourComponent],
      imports: [/* required modules */]
    }).compileComponents();

    fixture = TestBed.createComponent(YourComponent);
    component = fixture.componentInstance;
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });

  // Add more tests here
});

Best Practices

  1. Use Descriptive Test Names

    // Good
it('should display error when username is missing', () => {});

// Bad
it('should work', () => {});

  2. Follow AAA Pattern

    • Arrange: Set up test data
    • Act: Execute the code
    • Assert: Verify the result

  3. Test One Thing at a Time Each test should verify a single behavior.

  4. Use beforeEach for Setup Common setup code should be in beforeEach blocks.

  5. Clean Up After Tests Use afterEach to clean up mocks and spies.

  6. Mock External Dependencies Always mock HTTP calls, external services, etc.

Test Configuration

Karma Configuration

Located at: src/karma.conf.js

Key Settings:

  • Framework: Jasmine
  • Browsers: Chrome, ChromeHeadless
  • Coverage Tool: karma-coverage
  • Reporters: progress, kjhtml, coverage

TypeScript Configuration for Tests

Located at: src/tsconfig.spec.json

Includes test-specific TypeScript settings.

CI/CD Integration

GitHub Actions Example

name: Run Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '20'
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm run test:ci
      - name: Generate coverage
        run: npm run test:coverage
      - name: Upload coverage
        uses: codecov/codecov-action@v2

Jenkins Pipeline Example

pipeline {
  agent any
  stages {
    stage('Install') {
      steps {
        sh 'npm ci'
      }
    }
    stage('Test') {
      steps {
        sh 'npm run test:ci'
      }
    }
    stage('Coverage') {
      steps {
        sh 'npm run test:coverage'
        publishHTML([
          reportDir: 'coverage/AngularUI',
          reportFiles: 'index.html',
          reportName: 'Coverage Report'
        ])
      }
    }
  }
}

Troubleshooting

Common Issues

1. Chrome Not Found

Error: Chrome binary not found

Solution:

# Use ChromeHeadless instead
npm run test:ci

2. Tests Timeout

Error: Timeout - Async callback was not invoked

Solution:

  • Increase timeout in karma.conf.js
  • Ensure all async operations complete
  • Use fakeAsync and tick() for testing async code

3. Module Not Found

Error: Cannot find module

Solution:

  • Ensure all required modules are imported in TestBed
  • Check that paths in tsconfig are correct
  • Run npm install to ensure dependencies are installed

4. Coverage Too Low

Error: Coverage thresholds not met

Solution:

  • Identify uncovered code in coverage report
  • Add tests for uncovered branches
  • Remove dead code if not needed

5. Memory Issues

Error: JavaScript heap out of memory

Solution:

# Increase memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm test

Debug Mode

Run tests with debugging:

# Chrome DevTools
ng test --browsers=Chrome --watch

# VS Code debugging
# Add launch.json configuration:
{
  "type": "chrome",
  "request": "attach",
  "name": "Karma Tests",
  "address": "localhost",
  "port": 9876,
  "pathMapping": {
    "/": "${workspaceRoot}",
    "/base/": "${workspaceRoot}/"
  }
}

Test Maintenance

Regular Tasks

  1. Weekly: Review failing tests
  2. Monthly: Update test dependencies
  3. Quarterly: Review and update test coverage goals
  4. After Major Changes: Update integration tests

Updating Tests After Angular Upgrade

When upgrading Angular:

  1. Update testing dependencies in package.json
  2. Update karma.conf.js if needed
  3. Run tests to identify breaking changes
  4. Update test code to use new APIs
  5. Verify coverage remains above thresholds

Performance Benchmarks

Target Performance Metrics

  • Component initialization: < 100ms
  • Form validation: < 10ms per validation
  • Change detection: < 50ms per cycle
  • E2E page load: < 3 seconds

Monitoring Performance

Run performance tests regularly:

ng test --include='**/performance.spec.ts'

Additional Resources

Documentation

Tools

Support

For questions or issues:

  1. Check this documentation first
  2. Review Angular testing documentation
  3. Search existing GitHub issues
  4. Create a new issue with reproduction steps

Version History

v19.0.0 (Current)

  • Updated to Angular 19.0.0
  • Added 190+ comprehensive test cases
  • Implemented performance testing suite
  • Enhanced integration test coverage
  • Updated E2E tests with accessibility checks
  • Improved code coverage to 80%+

Previous Versions

  • v7.2.0: Initial test implementation