Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
TestGen is an AI-powered platform designed to automatically generate and execute test cases for code repositories. The system integrates with Google's Gemini AI to analyze code and produce comprehensive test suites. Its architecture is composed of a frontend application, a backend processing system, and external API integrations.
The project features two distinct backend implementations: a traditional server-side Go backend and a modern client-side backend that runs entirely in the browser. This dual-architecture approach offers flexibility in deployment, with the client-side version simplifying hosting by removing the need for a dedicated server. Both architectures follow a similar workflow: analyzing a code repository, generating a context for the AI, interacting with the Gemini API to create tests, and finally, executing those tests in the frontend.
Sources: README.md:3-5, testgen/CLIENT_BACKEND.md:5-11
High-Level System Design
The TestGen platform is structured around three primary components: a React-based frontend, a backend service (either Go or client-side), and Google's Gemini AI service. The frontend provides the user interface for repository input and test visualization. The backend is responsible for fetching repository code and preparing it for the AI. The Gemini API is the core intelligence, generating test cases based on the provided code context.
The following diagram illustrates the high-level interaction between these components.
This diagram shows the flow of data from the user's interaction with the frontend to the backend, which then communicates with external APIs (GitHub and Google Gemini) before returning the results.
Sources: README.md:15-25, testgen/CLIENT_BACKEND.md:7-11
Core Workflows
The system operates through three main workflows: Repository Analysis, Test Generation, and Test Execution.
1. Repository Analysis Workflow
This workflow begins with the user providing a GitHub URL. The system then fetches, filters, and processes the repository's files to create a code context.
2. Test Generation Workflow
Using the generated code context and a user-provided Gemini API key, the system requests test cases from the Gemini AI.
3. Test Execution Workflow
The generated test cases are executed in a sandboxed environment within the browser, with results validated against expected outcomes.
Frontend Architecture (testgen/)
The frontend is a single-page application built with React, TypeScript, and Vite. It provides the entire user interface for interacting with the TestGen system.
Sources: README.md:62-68
Technology Stack
- UI Framework: React 18
- Language: TypeScript
- Build Tool: Vite
- Styling: Tailwind CSS & shadcn/ui
- Icons: Lucide React
Sources: README.md:63-68, testgen/package.json:15-46
Key Components
| Component | File | Description |
|---|---|---|
Dashboard.tsx | src/pages/Dashboard.tsx | The main application page, containing tabs for generating, executing, and viewing test results, as well as settings. |
TestRunner.tsx | src/components/TestRunner.tsx | An engine for executing generated JavaScript tests in the browser. It includes a library of mock functions and validates results. |
ApiService | src/lib/api.ts | A service class that centralizes communication with the backend, whether it's the Go server or the client-side implementation. |
ClientBackend | src/lib/backend.ts | The client-side backend implementation that uses the GitHub and Gemini APIs directly from the browser. |
Sources: README.md:72-90, testgen/src/pages/Dashboard.tsx, testgen/src/components/TestRunner.tsx
The following diagram shows the interaction between the main frontend components.
Backend Architecture
TestGen has two backend implementations. The original is a Go-based server, while the newer version is a "client-side backend" written in TypeScript that runs in the browser.
Go Backend (testgen-backend/)
The Go backend is a simple HTTP server responsible for cloning repositories, creating a context file, and proxying requests to the Gemini API.
API Endpoints
| Method | Endpoint | Request Body | Response Body | Description |
|---|---|---|---|---|
POST | /api/clone-repo | { "repoUrl": "string" } | RepoResponse | Clones a GitHub repo, filters files, and creates a context file. |
POST | /api/generate-tests | GeminiRequest | GeminiResponse | Sends the code context to the Gemini API to generate tests. |
GET | /api/context/{owner}/{repo} | N/A | { "context": "string" } | Retrieves a previously generated context file. |
Sources: README.md:100-141, testgen-backend/main.go:315-330, 423-441, 597-600
Repository Cloning Sequence (Go Backend)
This sequence diagram shows how the Go backend handles a repository clone request.
Sources: testgen-backend/main.go:315-394
Client-Side Backend (testgen/src/lib/backend.ts)
To simplify deployment, a client-side backend was developed. It replaces the Go server by interacting with the GitHub and Gemini APIs directly from the browser.
Benefits:
- No Server Required: Runs entirely in the browser.
- Simplified Deployment: Only the static frontend needs to be deployed.
- Cost-Effective: No backend server costs.
Considerations:
- CORS Limitations: GitHub API calls can be subject to CORS policies.
- API Rate Limits: Subject to GitHub's unauthenticated API rate limits (60 requests/hour).
Sources: testgen/CLIENT_BACKEND.md:13-31
Repository Cloning Sequence (Client-Side Backend)
This sequence diagram shows the client-side process for fetching repository files.
Data Structures
The communication between the frontend and backend, as well as with the Gemini API, relies on several key data structures.
RepoResponse
This object is returned after a successful repository clone/fetch operation.
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the operation was successful. |
message | string | A status message. |
filesCount | number | The number of relevant files processed. |
contextPath | string | Path to the generated context file (Go backend only). |
files | FileContent[] | An array of file objects with their path and content. |
Sources: testgen-backend/main.go:21-28, testgen/src/lib/backend.ts:13-20
GeminiTestCase
This represents a single test case as generated by the Gemini API.
| Field | Type | Description |
|---|---|---|
id | string | A unique identifier for the test. |
name | string | A descriptive name for the test. |
description | string | A detailed explanation of the test's purpose. |
input | any | The input data for the function being tested. |
expected | any | The expected output or result. |
code | string | The function or code snippet being tested. |
testType | string | The type of test (e.g., 'unit', 'integration'). |
priority | string | The test's priority (e.g., 'high', 'medium'). |
Sources: testgen-backend/main.go:30-40, testgen/src/lib/backend.ts:27-37