Add Vitest Testing Framework Setup with Comprehensive Configuration and Documentation

[Copilot]

Overview

This PR implements a complete Vitest testing framework for the unthread-webhook-server project, providing a fast, modern testing solution with first-class TypeScript support and comprehensive coverage reporting capabilities.

What's Changed

🧪 Testing Infrastructure

Vitest Installation

• Added [email protected] as the core testing framework
• Added @vitest/[email protected] for interactive test debugging
• Added @vitest/[email protected] for V8-based coverage reporting

Test Scripts (using yarn as per project standards)

yarn test              # Run all tests once (CI/CD friendly)
yarn test:watch        # Watch mode for development
yarn test:ui           # Interactive UI mode
yarn test:coverage     # Generate coverage reports

Configuration

• Created vitest.config.ts with:
  • Node.js environment setup
  • Global test utilities enabled
  • V8 coverage provider with 80% thresholds across all metrics
  • Multiple coverage formats (text, json, html, lcov)
  • Path aliases matching TypeScript configuration

📝 Documentation

README.md
Added a comprehensive Testing section documenting:

• How to run tests in different modes
• Test file organization pattern (co-located tests)
• Coverage requirements and standards

TESTING.md (New)
Created extensive testing guide with:

• Framework overview and benefits
• Quick start guide for all test commands
• Best practices and patterns
• Code examples for unit tests, mocks, and async testing
• VS Code integration instructions
• Troubleshooting guide and learning resources

CONTRIBUTING.md
Updated to reflect the new testing infrastructure:

• Enhanced testing guidelines with automated testing requirements
• Added test commands to development workflow
• Updated code review checklist with test-related requirements

🔧 VS Code Integration

• Created .vscode/settings.json with Vitest configuration
• Updated .vscode/extensions.json to recommend vitest.explorer extension
• Enables inline test results and debugging within VS Code

🚀 CI/CD Integration

Validate Workflow (validate.yml)

• Added test execution for all pull requests
• Added coverage generation step
• Tests run before build to catch issues early

Build Workflow (build.yml)

• Created dedicated test job for dev branch pushes
• Build job now depends on test job (fails fast if tests fail)
• Includes type checking, tests, and coverage generation

📦 Configuration Updates

TypeScript

• Updated tsconfig.json to exclude test files from production build
• Ensures clean dist/ output without test artifacts

Git

• Updated .gitignore to exclude coverage artifacts and test results

🧪 Example Test

Created src/utils/signature.test.ts demonstrating:

• Basic test structure with describe/it/expect
• Co-located test pattern
• Simple assertions to verify setup

Benefits

• Fast Execution: Vitest is significantly faster than Jest
• TypeScript Native: First-class TypeScript support out of the box
• ESM Support: Modern ES modules support
• Developer Experience: Interactive UI, watch mode, and excellent error messages
• Coverage: Built-in V8 coverage with configurable thresholds
• CI/CD Ready: Integrated into existing GitHub Actions workflows

Verification

All commands tested and working:

• ✅ yarn test - Runs tests successfully
• ✅ yarn test:watch - Watch mode works correctly
• ✅ yarn test:ui - Interactive UI launches properly
• ✅ yarn test:coverage - Coverage reports generate in multiple formats
• ✅ yarn type-check - TypeScript compilation passes
• ✅ yarn build - Production build succeeds without test files

Coverage Configuration

• Thresholds: 80% for lines, functions, branches, and statements
• Reports: Generated in text, JSON, HTML, and LCOV formats
• Exclusions: node_modules, dist, config files, and type definitions properly excluded

Next Steps

With this foundation in place, contributors can now:

1. Write tests for existing functionality
2. Ensure new features include test coverage
3. Use interactive UI for test debugging
4. Track coverage progress towards the 80% threshold

This implementation provides a production-ready testing foundation that aligns with modern TypeScript development practices while maintaining compatibility with the project's existing tooling and workflows.

Original prompt

Add Vitest Testing Framework Setup

Vitest Testing Framework Setup

Objective

Implement Vitest as the testing framework for the unthread-webhook-server project, providing a fast, modern testing solution with TypeScript support and coverage reporting capabilities.

Core Requirements

1. Vitest Installation

Install Vitest and essential testing dependencies:

• vitest - Core testing framework
• @vitest/ui - Optional interactive UI for test debugging
• @vitest/coverage-v8 - Coverage reporting (V8 provider)
• @types/node - Already installed, ensure compatibility

2. Package.json Scripts Configuration

Add the following test scripts using pnpm package manager:

"scripts": {
  "test": "vitest run",              // One-time execution (CI/CD friendly)
  "test:watch": "vitest",            // Watch mode for development
  "test:ui": "vitest --ui",          // Interactive UI mode
  "test:coverage": "vitest run --coverage"  // Generate coverage reports
}

Expected Behavior:

• pnpm test → Runs all tests once and exits
• pnpm test:watch → Runs tests in watch mode (auto re-run on changes)
• pnpm test:ui → Opens interactive test UI in browser
• pnpm test:coverage → Generates coverage reports

3. Vitest Configuration File

Create vitest.config.ts at project root:

import { defineConfig } from 'vitest/config';
import path from 'path';

export default defineConfig({
  test: {
    // Test environment
    environment: 'node',
    
    // Global test setup
    globals: true,
    
    // Coverage configuration
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html', 'lcov'],
      exclude: [
        'node_modules/',
        'dist/',
        '**/*.config.*',
        '**/*.d.ts',
        '**/types/**',
        'coverage/**'
      ],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 80,
        statements: 80
      }
    },
    
    // Test file patterns
    include: ['**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
    exclude: ['node_modules', 'dist', '.idea', '.git', '.cache'],
    
    // Timeouts
    testTimeout: 10000,
    hookTimeout: 10000,
  },
  
  // Path resolution to match tsconfig
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

4. Test Directory Structure

Create basic test structure (setup only, no actual tests yet):

tests/
├── unit/           # Unit tests
├── integration/    # Integration tests
└── setup.ts        # Global test setup file (if needed)

OR use co-located tests:

src/
├── __tests__/      # Tests alongside source code
├── utils/
│   └── signature.test.ts  # Example test location

Recommendation: Use co-located tests (src/**/*.test.ts) for better maintainability.

5. Example Test File

Create ONE simple example test to verify setup works:

File: src/utils/signature.test.ts (or similar location)

import { describe, it, expect } from 'vitest';

describe('Vitest Setup Verification', () => {
  it('should run tests successfully', () => {
    expect(true).toBe(true);
  });

  it('should handle basic assertions', () => {
    const sum = (a: number, b: number) => a + b;
    expect(sum(2, 3)).toBe(5);
  });
});

6. TypeScript Configuration Updates

Ensure tsconfig.json includes test files and Vitest types:

{
  "compilerOptions": {
    "types": ["node", "vitest/globals"]
  },
  "include": ["src/**/*", "**/*.test.ts", "**/*.spec.ts"],
  "exclude": ["node_modules", "dist"]
}

7. Git Ignore Updates

Add coverage and test artifacts to .gitignore:

# Test coverage
coverage/
*.lcov
.vitest/

# Test results
test-results/

8. CI/CD Integration Preparation

Add placeholder for GitHub Actions workflow (or update existing):

# Future CI/CD integration
- name: Run Tests
  run: pnpm test

- name: Generate Coverage
  run: pnpm test:coverage
  
- name: Upload Coverage
  uses: codecov/codecov-action@v3
  with:
    files: ./coverage/lcov.info

9. Documentation Updates

Update README.md with Testing section:

## Testing

This project uses [Vitest](https://vitest.dev/) for fast, modern testing.

### Running Tests

```bash
# Run all tests (one-time)
pnpm test

# Run tests in watch mode (development)
pnpm test:watch

# Run tests with interactive UI
pnpm test:ui

# Generate coverage report
pnpm test:coverage

Writing Tests

Tests are co-located with source files using the .test.ts suffix:

src/
├── utils/
│   ├── signature.ts
│   └── signature.test.ts

Coverage Requirements

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

**Create `TESTING.md` documentation:**
Document testing standards, patterns, and best practices for the project.

#### 10. VS Code Integration
Add recommended extensions and settings:

**`.vscode/settings.json`** (if it doesn't exist):
```json
{
  "vitest.enable": true,
  "vites...

</details>
Created from VS Code via the [GitHub Pull Request](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension.

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click [here](https://survey3.medallia.com/?EAHeSx-AP01bZqG0Ld9QLQ) to start the survey.