CommunityRule/community-rule

Fork 0

Files

T

adilallo 9b7890ca64 Update testing runner

2025-08-29 08:24:53 -06:00

16 KiB

Raw Blame History

Testing Framework Documentation

📋 Table of Contents

Overview
Quick Start
Test Structure
Unit & Integration Testing
E2E Testing
Visual Regression Testing
Performance Testing
Storybook Testing
CI/CD Pipeline
Development Workflow
Best Practices
Troubleshooting
Monitoring & Metrics

🎯 Overview

This project uses a comprehensive testing framework with multiple layers of testing to ensure code quality, functionality, and visual consistency across all browsers and devices.

Testing Stack

Unit/Integration: Vitest + JSDOM + React Testing Library
E2E: Playwright (Chromium, Firefox, WebKit, Mobile)
Visual Regression: Playwright Screenshots
Performance: Lighthouse CI
Accessibility: Axe-core + Storybook
CI/CD: Gitea Actions

Test Coverage

✅ 124 Unit Tests (8 components + 1 integration)
✅ 308 E2E Tests (4 browsers × 77 tests)
✅ 92 Visual Regression Screenshots
✅ Performance Budgets
✅ Accessibility Compliance

🚀 Quick Start

Prerequisites

# Install dependencies
npm install

# Install Playwright browsers
npx playwright install

Running Tests

# All unit tests with coverage
npm test

# Unit tests in watch mode
npm run test:watch

# E2E tests
npm run e2e

# Performance tests
npm run lhci

# Storybook tests
npm run test:sb

📁 Test Structure

tests/
├── unit/                          # Component unit tests
│   ├── Button.test.jsx           # 113 lines
│   ├── HeroBanner.test.jsx       # 143 lines
│   ├── FeatureGrid.test.jsx      # 146 lines
│   ├── LogoWall.test.jsx         # 170 lines
│   ├── NumberedCards.test.jsx    # 196 lines
│   ├── RuleStack.test.jsx        # 207 lines
│   ├── QuoteBlock.test.jsx       # 223 lines
│   └── AskOrganizer.test.jsx     # 294 lines
├── integration/                   # Component integration tests
│   └── ContentLockup.integration.test.jsx  # 157 lines
└── e2e/                          # End-to-end tests
    ├── homepage.spec.ts          # 18 tests per browser
    ├── user-journeys.spec.ts     # 13 tests per browser
    ├── edge-cases.spec.ts        # 18 tests per browser
    └── visual-regression.spec.ts # 23 tests per browser

🚀 Runner Management Scripts

community-rule/
├── start-runner.sh               # Start Gitea Actions runner
├── stop-runner.sh                # Stop Gitea Actions runner
├── status-runner.sh              # Check runner status
├── config.yaml                   # Runner configuration
└── act_runner                    # Gitea Actions runner binary

🧪 Unit & Integration Testing

Framework

Vitest: Fast unit test runner
JSDOM: Browser environment simulation
React Testing Library: Component testing utilities
MSW: API mocking

Configuration

// vitest.config.js
export default defineConfig({
  plugins: [react({ jsxRuntime: "automatic" })],
  test: {
    environment: "jsdom",
    setupFiles: ["./vitest.setup.js"],
    coverage: {
      provider: "v8",
      thresholds: { lines: 85, functions: 85, statements: 85, branches: 80 },
    },
  },
});

Writing Unit Tests

// tests/unit/Component.test.jsx
import { render, screen } from "@testing-library/react";
import { describe, test, expect, afterEach } from "vitest";
import { cleanup } from "@testing-library/react";
import Component from "../../app/components/Component";

describe("Component", () => {
  afterEach(() => cleanup());

  test("renders correctly", () => {
    render(<Component />);
    expect(screen.getByRole("button")).toBeInTheDocument();
  });
});

Available Scripts

npm test              # Run all tests with coverage
npm run test:watch    # Run tests in watch mode
npm run test:ui       # Run tests with UI

🌐 E2E Testing

Framework

Playwright: Cross-browser E2E testing
Browsers: Chromium, Firefox, WebKit, Mobile
Accessibility: Axe-core integration

Configuration

// playwright.config.ts
export default defineConfig({
  testDir: "./tests/e2e",
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
    { name: "mobile", use: { ...devices["iPhone 12"] } },
  ],
});

Test Categories

1. Homepage Tests (18 tests per browser)

Page loading and sections
Component functionality
Navigation and interactions
Responsive design
Accessibility compliance
Performance metrics

2. User Journey Tests (13 tests per browser)

Complete user workflows
Feature exploration
Contact flows
Learning paths
Navigation patterns

3. Edge Cases Tests (18 tests per browser)

Network conditions
Browser behavior
Error scenarios
Accessibility edge cases
Performance under stress

4. Visual Regression Tests (23 tests per browser)

Full page screenshots
Component screenshots
Responsive screenshots
Interactive states

Writing E2E Tests

// tests/e2e/example.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Feature", () => {
  test.beforeEach(async ({ page }) => {
    await page.goto("/");
  });

  test("should work correctly", async ({ page }) => {
    await expect(page).toHaveTitle(/CommunityRule/);
    await expect(page.locator("h1")).toBeVisible();
  });
});

Available Scripts

npm run e2e           # Run all E2E tests
npm run e2e:ui        # Run E2E tests with UI
npm run e2e:serve     # Start dev server and run tests

🎨 Visual Regression Testing

Overview

Visual regression testing ensures UI consistency across browsers and prevents unintended visual changes.

Screenshots Generated

Full page screenshots (mobile, tablet, desktop)
Component screenshots (hero, logo wall, cards, etc.)
Interactive states (hover, focus, loading, error)
Special modes (dark mode, high contrast, reduced motion)

Baseline Screenshots

tests/e2e/visual-regression.spec.ts-snapshots/
├── homepage-full-chromium-darwin.png
├── homepage-mobile-chromium-darwin.png
├── hero-banner-chromium-darwin.png
├── logo-wall-chromium-darwin.png
└── ... (92 total screenshots)

Managing Visual Changes

# Update baselines after intentional changes
npx playwright test tests/e2e/visual-regression.spec.ts --update-snapshots

# Run visual regression tests
npx playwright test tests/e2e/visual-regression.spec.ts

Cross-Browser Coverage

Chromium (Chrome/Edge)
Firefox
WebKit (Safari)
Mobile (Mobile Chrome)

⚡ Performance Testing

Framework

Lighthouse CI: Automated performance testing
Performance Budgets: Defined thresholds

Configuration

// lighthouserc.json
{
  "ci": {
    "collect": {
      "url": ["http://localhost:3000"],
      "startServerCommand": "npm run preview"
    },
    "assert": {
      "assertions": {
        "categories:performance": ["warn", { "minScore": 0.9 }],
        "categories:accessibility": ["error", { "minScore": 0.95 }]
      }
    }
  }
}

Performance Metrics

Core Web Vitals: LCP, FID, CLS
Performance Score: Overall performance rating
Accessibility Score: WCAG compliance
Best Practices: Web development standards
SEO Score: Search engine optimization

Available Scripts

npm run lhci          # Run Lighthouse CI

📚 Storybook Testing

Framework

Storybook: Component development environment
@storybook/test-runner: Automated testing
@storybook/test: Testing utilities

Configuration

// .storybook/preview.js
export const parameters = {
  a11y: { element: "#storybook-root", manual: false },
  viewport: { defaultViewport: "responsive" },
  chromatic: { viewports: [360, 768, 1024, 1440] },
};

Testing Features

Accessibility Testing: Automated WCAG compliance
Visual Testing: Component screenshots
Interaction Testing: User interactions
Responsive Testing: Multiple viewports

Available Scripts

npm run storybook     # Start Storybook dev server
npm run test:sb       # Run Storybook tests
npm run build-storybook # Build Storybook

🔄 CI/CD Pipeline

Gitea Actions Workflow

Location: .gitea/workflows/ci.yml

Pipeline Jobs

1. Unit Tests

Node.js versions: 18, 20
Coverage reporting: Codecov integration
Parallel execution: Matrix strategy

2. E2E Tests

Browsers: Chromium, Firefox, WebKit
Parallel execution: Matrix strategy
Artifact upload: Test results and reports

3. Visual Regression Tests

Screenshot comparison: Baseline vs current
Artifact upload: Screenshot diffs
Cross-browser validation

4. Performance Tests

Lighthouse CI: Performance budgets
Core Web Vitals: Monitoring
Accessibility compliance

5. Storybook Tests

Component testing: Automated tests
Accessibility validation: WCAG compliance
Build verification: Storybook compilation

6. Lint & Format

ESLint: Code quality
Prettier: Code formatting
Type checking: TypeScript validation

7. Build Verification

Next.js build: Application compilation
Storybook build: Documentation compilation

Triggers

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

🛠 Development Workflow

1. Feature Development

# Create feature branch
git checkout -b feature/new-component

# Write tests first (TDD)
npm run test:watch

# Implement feature
# Ensure tests pass

# Run E2E tests
npm run e2e

# Commit changes
git add .
git commit -m "feat: add new component with tests"

2. Manual Runner Management

The Gitea Actions runner is managed manually to save resources and provide control over when CI runs.

Start Runner (Before Creating PR)

# Start the runner to execute CI jobs
./start-runner.sh

Check Runner Status

# Check if runner is running and see recent logs
./status-runner.sh

Stop Runner (After PR Complete)

# Stop the runner to free up resources
./stop-runner.sh

Complete PR Workflow

# 1. Start runner
./start-runner.sh

# 2. Create Pull Request
# Go to repository → New Pull Request

# 3. Monitor CI progress
./status-runner.sh
# Or check Gitea Actions page

# 4. Stop runner when done
./stop-runner.sh

2. Pull Request Process

Create PR → CI pipeline starts automatically
Review CI Results → All 7 jobs must pass
Check Coverage → Ensure >85% coverage
Review Visual Changes → Check screenshot diffs
Merge → Only if all checks pass

3. Visual Changes

# Make visual changes
# Run visual regression tests
npm run e2e:serve
npx playwright test tests/e2e/visual-regression.spec.ts

# If changes are intentional, update baselines
npx playwright test tests/e2e/visual-regression.spec.ts --update-snapshots

4. Performance Monitoring

# Check performance before deploying
npm run lhci

# Review performance budgets
# Update lighthouserc.json if needed

📋 Best Practices

1. Test-Driven Development

Write tests before implementation
Use descriptive test names
Test edge cases and error scenarios
Maintain high test coverage

2. Component Testing

// Good: Test behavior, not implementation
test("shows error message when form is invalid", () => {
  render(<Form />);
  fireEvent.click(screen.getByRole("button"));
  expect(screen.getByText("Please fill all fields")).toBeInTheDocument();
});

// Avoid: Testing implementation details
test("calls onSubmit with form data", () => {
  const mockSubmit = vi.fn();
  render(<Form onSubmit={mockSubmit} />);
  // Implementation details...
});

3. E2E Testing

Test user workflows, not technical details
Use semantic selectors (role, text, label)
Test accessibility features
Include error scenarios

4. Visual Regression

Update baselines only for intentional changes
Review screenshot diffs carefully
Test across multiple viewports
Consider animation states

5. Performance Testing

Set realistic performance budgets
Monitor Core Web Vitals
Test on different network conditions
Regular performance audits

🔧 Troubleshooting

Common Issues

1. Unit Tests Failing

# Run tests locally
npm test

# Check for:
# - Missing imports
# - Incorrect assertions
# - Component changes
# - Test environment issues

2. E2E Tests Failing

# Run locally first
npm run e2e:serve
npm run e2e

# Common issues:
# - Selector changes
# - Component structure changes
# - Network issues
# - Browser compatibility

3. Visual Regression Failing

# Check if changes are intentional
npx playwright test tests/e2e/visual-regression.spec.ts

# Update baselines if needed
npx playwright test tests/e2e/visual-regression.spec.ts --update-snapshots

# Review screenshot diffs in CI artifacts

4. Performance Tests Failing

# Run locally
npm run lhci

# Check performance budgets in lighthouserc.json
# Optimize slow components
# Review bundle size

5. CI Pipeline Issues

# Check Gitea Actions logs
# Verify workflow configuration
# Check for missing dependencies
# Review environment variables

Debug Commands

# Debug unit tests
npm run test:ui

# Debug E2E tests
npm run e2e:ui

# Debug with browser dev tools
npx playwright test --debug

# Run specific test file
npx playwright test tests/e2e/homepage.spec.ts

# Run tests in headed mode
npx playwright test --headed

📊 Monitoring & Metrics

1. Test Coverage

Target: >85% line coverage
Monitoring: Codecov integration
Trends: Track coverage over time
Reports: Available in CI artifacts

2. Performance Metrics

Core Web Vitals: LCP < 2.5s, FID < 100ms, CLS < 0.1
Performance Score: >90
Accessibility Score: >95
Monitoring: Lighthouse CI reports

3. Visual Regression

Baseline Screenshots: 92 total
Cross-browser Coverage: 4 browsers
Responsive Testing: 4 viewports
Monitoring: Screenshot diffs in CI

4. E2E Test Results

Total Tests: 308 across 4 browsers
Success Rate: Monitor test stability
Execution Time: Track performance
Reports: Available in CI artifacts

5. CI Pipeline Health

Job Success Rate: Monitor pipeline stability
Execution Time: Track build performance
Resource Usage: Monitor CI costs
Failure Analysis: Identify common issues

📚 Additional Resources

Documentation

Tools

Codecov - Coverage reporting
Axe-core - Accessibility testing
MSW - API mocking

Best Practices

Last Updated: December 2024
Framework Version: Next.js 15 + React 19 + Tailwind 4 + Storybook 9

16 KiB Raw Blame History Unescape Escape

Testing Framework Documentation

📋 Table of Contents

🎯 Overview

Testing Stack

Test Coverage

🚀 Quick Start

Prerequisites

Running Tests

📁 Test Structure

🚀 Runner Management Scripts

🧪 Unit & Integration Testing

Framework

Configuration

Writing Unit Tests

Available Scripts

🌐 E2E Testing

Framework

Configuration

Test Categories

1. Homepage Tests (18 tests per browser)

2. User Journey Tests (13 tests per browser)

3. Edge Cases Tests (18 tests per browser)

4. Visual Regression Tests (23 tests per browser)

Writing E2E Tests

Available Scripts

🎨 Visual Regression Testing

Overview

Screenshots Generated

Baseline Screenshots

Managing Visual Changes

Cross-Browser Coverage

⚡ Performance Testing

Framework

Configuration

Performance Metrics

Available Scripts

📚 Storybook Testing

Framework

Configuration

Testing Features

Available Scripts

🔄 CI/CD Pipeline

Gitea Actions Workflow

Pipeline Jobs

1. Unit Tests

2. E2E Tests

3. Visual Regression Tests

4. Performance Tests

5. Storybook Tests

6. Lint & Format

7. Build Verification

Triggers

🛠 Development Workflow

1. Feature Development

2. Manual Runner Management

Start Runner (Before Creating PR)

Check Runner Status

Stop Runner (After PR Complete)

Complete PR Workflow

2. Pull Request Process

3. Visual Changes

4. Performance Monitoring

📋 Best Practices

1. Test-Driven Development

2. Component Testing

3. E2E Testing

4. Visual Regression

5. Performance Testing

🔧 Troubleshooting

Common Issues

1. Unit Tests Failing

2. E2E Tests Failing

3. Visual Regression Failing

4. Performance Tests Failing

5. CI Pipeline Issues

Debug Commands

📊 Monitoring & Metrics

1. Test Coverage

2. Performance Metrics

16 KiB

Raw Blame History