How to Perform Unit Tests for FckSignups: A Complete Vitest Setup Guide

Run unit tests for FckSignups using Vitest with jsdom for React components and direct handler testing for the Cloudflare Worker, configured via vite.config.mts.

FckSignups is a modern Vite-powered React application built in TypeScript, split between UI components under src/components/ and a server-side Cloudflare Worker in cloudflare-worker/. Performing unit tests for FckSignups requires a unified testing stack that handles both the frontend and edge runtime. This guide walks through installing Vitest with @testing-library/react, configuring the test environment, writing component and worker tests, and running them efficiently.

Prerequisites and Source Code Structure

Before setting up tests, understand the repository layout as defined in BraveOPotato/FckSignups:

• Core UI components: src/components/ (e.g., ToolCard, Header, Footer)
• Hooks and utilities: src/hooks/ and src/utils/ (e.g., useTools, useReport)
• Worker handlers: cloudflare-worker/urlHandlers/ (e.g., handleSuggestTool)

The project uses Vite as its build tool, making Vitest the natural choice for unit testing—it reuses Vite's configuration and provides instant feedback during development.

Installing Vitest and Testing Dependencies

Add the required dev dependencies to enable unit testing across both frontend and worker code:

npm install -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom

These packages provide:

• vitest: The test runner with Vite-native HMR
• @testing-library/react: DOM testing utilities for React components
• @testing-library/jest-dom: Custom matchers like toBeInTheDocument()
• @testing-library/user-event: Simulated user interactions
• jsdom: Browser-like environment for component tests

Configuring Vitest in vite.config.mts

Extend the existing Vite configuration to include Vitest settings. In vite.config.mts, add a test block:

// vite.config.mts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: './src/setupTests.ts',
    css: true,
    coverage: {
      reporter: ['text', 'json', 'html'],
    },
  },
});

Key configuration options:

Option	Purpose
environment: 'jsdom'	Runs DOM-dependent tests in a browser-like environment
globals: true	Enables global describe, test, expect without imports
setupFiles	Loads src/setupTests.ts before each test file
css: true	Processes CSS imports to prevent test failures

Creating the Global Test Setup

Create src/setupTests.ts to register jest-dom matchers for cleaner assertions:

// src/setupTests.ts
import '@testing-library/jest-dom';

This file runs once before each test suite, making matchers like toBeInTheDocument() and toHaveClass() available globally.

Adding Test Scripts to package.json

Update package.json with convenient test commands:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

• npm test: Single execution for CI pipelines
• npm run test:watch: Continuous execution with hot reload for TDD

Writing Unit Tests for React Components

Place test files adjacent to components using the .test.tsx naming convention. Here's how to test the ToolCard component located at src/components/Home/Tools/ToolCard/ToolCard.tsx:

// src/components/Home/Tools/ToolCard/ToolCard.test.tsx
import { render, screen } from '@testing-library/react';
import ToolCard from './ToolCard';

test('renders tool name and description', () => {
  const sampleTool = {
    id: 'test-tool',
    name: 'Test Tool',
    description: 'A tool used for testing',
    icon: '🔧',
  };

  render(<ToolCard tool={sampleTool} />);
  expect(screen.getByText('Test Tool')).toBeInTheDocument();
  expect(screen.getByText('A tool used for testing')).toBeInTheDocument();
});

Testing patterns for FckSignups components:

• Props verification: Render with sample data and assert DOM output
• Event handling: Use @testing-library/user-event for click/change simulations
• Hook isolation: Mock useTools or useReport when testing consumers

Testing Cloudflare Worker Handlers

The worker code in cloudflare-worker/ exports pure TypeScript functions that can be unit-tested directly without a full runtime. Test the handleSuggestTool handler from cloudflare-worker/urlHandlers/handleSuggestTool.ts:

// cloudflare-worker/urlHandlers/handleSuggestTool.test.ts
import { handleSuggestTool } from './handleSuggestTool';
import type { FetchEvent } from '@cloudflare/workers-types';

test('suggest tool returns 200 with valid input', async () => {
  const request = new Request('https://example.com/suggest', {
    method: 'POST',
    body: JSON.stringify({ name: 'Test Tool', url: 'https://example.com' }),
  });
  
  const mockEvent = { request } as FetchEvent;
  const response = await handleSuggestTool(mockEvent);
  
  expect(response.status).toBe(200);
});

For tests requiring full Cloudflare runtime APIs (KV, Durable Objects), install miniflare as a dev dependency and use its Miniflare instance in test setup.

Running FckSignups Unit Tests

Execute tests using the configured npm scripts:

Command	Behavior
npm test	Single run, exits with code on failure
npm run test:watch	Interactive watch mode with file watching
npx vitest --coverage	Generate coverage reports as configured

Vitest automatically discovers files matching **/*.test.{ts,tsx} patterns, compiles TypeScript through Vite's pipeline, and executes them in parallel.

Troubleshooting Common Setup Issues

• CSS import errors: Ensure css: true is set in vite.config.mts test config
• Missing DOM matchers: Verify src/setupTests.ts is correctly referenced in setupFiles
• Worker type errors: Install @cloudflare/workers-types for handler type definitions
• Module resolution failures: Check that tsconfig.json paths align with Vitest's resolver

Summary

• Install Vitest with React Testing Library and jsdom for frontend unit tests
• Extend vite.config.mts with a test block specifying jsdom environment and setup files
• Create src/setupTests.ts to globally register jest-dom matchers
• Add npm scripts for both CI (vitest run) and development (vitest) workflows
• Co-locate .test.tsx files next to components using ToolCard.test.tsx pattern
• Test worker handlers directly by importing from cloudflare-worker/urlHandlers/
• Use miniflare when full Cloudflare runtime simulation is required

Frequently Asked Questions

What test runner does FckSignups use?

FckSignups uses Vitest, which leverages the existing Vite configuration for zero-overhead TypeScript compilation and fast test execution.

Can I use Jest instead of Vitest for FckSignups?

While possible, Vitest is strongly recommended because it reuses vite.config.mts, eliminating duplicate configuration for aliases, plugins, and transforms already defined for the build.

Where should test files be placed in FckSignups?

Place test files next to the source file they cover, using the .test.tsx or .test.ts suffix. For example, ToolCard.test.tsx belongs in the same directory as ToolCard.tsx.

How do I test the Cloudflare Worker without deploying?

Import handler functions directly from cloudflare-worker/urlHandlers/ and invoke them with mocked FetchEvent objects. For integration tests requiring KV or other Cloudflare APIs, use the miniflare package to simulate the runtime locally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}