Testing Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• vitest.config.ts
• tests/App.test.tsx
• tests/youtubeService.test.ts
• tests/api_test.py
• package.json
• api/index.py

The project employs a dual-stack testing strategy, covering both the TypeScript/React frontend and the Python/FastAPI backend. The approach focuses on unit and integration tests, utilizing mocking to isolate components and services. The primary tools are Vitest for the frontend and Pytest for the backend.

This strategy ensures that both client-side logic and server-side API endpoints are independently verified for correctness, error handling, and adherence to specified contracts. Test execution is managed via npm scripts, which can run frontend tests, backend tests, or both.

Testing Toolchain

The project leverages a combination of frameworks and libraries to facilitate testing across the frontend and backend.

Test Execution

Test suites are executed using npm scripts defined in package.json.

Script	Command	Description
test	vitest	Runs the frontend (Vitest) test suite.
test:python	pytest	Runs the backend (Pytest) test suite.
test:all	pnpm test run && pnpm test:python	Executes both the frontend and backend test suites sequentially.

Sources: package.json:12-14

Key Dependencies

The testing framework relies on the following key development dependencies:

Package	Usage
vitest	The primary test runner for the frontend.
jsdom	Provides a simulated DOM environment for React component tests.
@testing-library/react	Provides utilities for testing React components.
@testing-library/jest-dom	Adds custom Jest DOM matchers for assertions.
pytest	The test runner for the Python backend.
fastapi.testclient	A client for testing FastAPI applications.

Sources: package.json:28-40, tests/api_test.py:2

Frontend Testing

Frontend testing is configured using Vitest and focuses on React components and services. The configuration is defined in vitest.config.ts.

Sources: vitest.config.ts

Vitest Configuration

The Vitest configuration specifies the testing environment and setup.

// vitest.config.ts:5-10
export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    setupFiles: ['./tests/setup.ts'],
    globals: true,
  },
  // ...
});

• Environment: jsdom is used to simulate a browser environment, enabling the rendering and interaction with React components.
• Setup Files: The tests/setup.ts file is executed before the test suite runs, which is a standard location for global test setup (though it is empty in this repository).
• Globals: globals: true automatically injects Vitest APIs (like describe, it, expect) into the global scope.

Sources: vitest.config.ts:7-9

Component Testing (App.test.tsx)

The main App component is tested to verify its rendering logic, state transitions, and user interactions. Child components and custom hooks are mocked to isolate the App component's own logic.

The following diagram illustrates the mocking strategy for the App component test.

This diagram shows that the App component test uses mocks for child components and custom hooks to control their behavior and focus testing on the App component itself.

Sources: tests/App.test.tsx:7-15, tests/App.test.tsx:21-36

Key test cases for App.test.tsx include:

• Verifying the initial "empty state" is rendered correctly.
• Simulating a click on the "Load Demo Video" button and asserting that the loadTranscript and loadNotes functions from the mocked hooks are called.
• Testing the error state display when the useTranscript hook returns an error.

Sources: tests/App.test.tsx:39-42, tests/App.test.tsx:44-53, tests/App.test.tsx:55-71

Service Testing (youtubeService.test.ts)

The YoutubeService is unit-tested to ensure its methods for fetching data and parsing URLs work as expected. The global fetch API is mocked to simulate network requests without making actual API calls.

The sequence diagram below shows the test flow for fetchTranscript success case.

This diagram shows how the test calls the service, which in turn calls the mocked fetch function and returns a predefined response, allowing the test to verify the service's data transformation logic.

Sources: tests/youtubeService.test.ts:15-33

Test cases for YoutubeService include:

• Success: fetchTranscript successfully calls the backend API and formats the response.
• Error: fetchTranscript throws an error if the backend API returns an error.
• Validation: fetchTranscript rejects video IDs that do not match the expected format.
• URL Parsing: extractVideoId correctly parses various YouTube URL formats.

Sources: tests/youtubeService.test.ts:15-33, tests/youtubeService.test.ts:35-42, tests/youtubeService.test.ts:44-46, tests/youtubeService.test.ts:48-53

Backend Testing

Backend testing uses Pytest and FastAPI's TestClient to send HTTP requests to the API endpoints and assert the responses.

Sources: tests/api_test.py

API Endpoint Testing (api_test.py)

The /api/transcript endpoint is tested for various scenarios. The youtube_transcript_api.YouTubeTranscriptApi class is patched using unittest.mock.patch to prevent actual calls to the YouTube API.

The flowchart below outlines the logic tested for the /api/transcript endpoint.

This diagram shows the different paths a request can take through the test, depending on the validity of the video ID and the mocked behavior of the external YouTubeTranscriptApi.

Sources: tests/api_test.py:20-80

Test Cases

The test suite in api_test.py covers the following scenarios:

Test Case	Mocked Behavior	Expected Outcome
test_get_transcript_success	get_transcript returns mock data.	200 OK with transcript data.
test_validation_error_short_id	N/A	422 Unprocessable Entity.
test_validation_error_long_id	N/A	422 Unprocessable Entity.
test_transcripts_disabled_error	get_transcript raises TranscriptsDisabled.	404 Not Found with error detail.
test_no_transcript_found_error	get_transcript raises NoTranscriptFound.	404 Not Found with error detail.
test_video_unavailable_error	get_transcript raises VideoUnavailable.	404 Not Found with error detail.
test_generic_exception	get_transcript raises a generic Exception.	500 Internal Server Error.

Sources: tests/api_test.py:20-80, api/index.py:75-93

This comprehensive set of tests ensures that the API endpoint is resilient and handles both successful requests and various failure modes gracefully.