How Tests Are Organized in Builder.io Agent Native: Co-Location and Feature-Centric Structure

Builder.io Agent Native co-locates test files with source code inside the templates/ directory, using a feature-centric structure where *.test.ts (or *.test.tsx) files sit next to the modules they verify.

The BuilderIO/agent-native repository follows a co-located testing pattern that keeps test suites adjacent to their corresponding source files. This organization strategy places all test files within the templates/ directory, mirroring the runtime folder structure of the application to ensure clear mapping between production code and its verification suite.

Co-Located Test Architecture in templates/

The test suite resides entirely within the top-level templates/ directory, which contains template versions of both client and server code. Unlike repositories that segregate tests into a separate tests/ folder, Builder.io Agent Native places *.test.ts and *.test.tsx files directly beside the modules they exercise.

This approach provides immediate visual correlation between implementation and verification. When developers navigate to templates/tasks/shared/, they find both the implementation and navigation.test.ts in the same directory, eliminating context switching between source and test folders.

Feature-Centric Directory Structure

The repository organizes tests by functional verticals, with each major feature area maintaining its own sub-folder under templates/:

• tasks/ – Tests for task-related utilities and UI components
• design/ – Tests for the design editor, shared design utilities, and server-side design endpoints
• calendar/ – Tests covering calendar UI components, hooks, and actions
• assets/ – Tests for asset handling, upload, and generation logic
• brain/ – Tests for LLM-driven evaluation workflows

Each sub-folder replicates the runtime architecture of its respective feature. For example, templates/design/ contains both shared/ utilities and server/ endpoints, with test files distributed accordingly throughout the hierarchy.

Test File Naming Conventions

All test files follow a strict naming pattern to enable easy discovery and glob matching:

• Unit and integration tests: *.test.ts
• React component tests: *.test.tsx

This convention allows the test runner to locate files using patterns like **/*.test.* while clearly distinguishing TypeScript logic tests from JSX component tests.

Directory Layout and File Paths

The following structure illustrates how tests are distributed across the templates/ directory:

templates/
├─ tasks/
│  └─ shared/
│     ├─ navigation.test.ts
│     ├─ boolean-param.test.ts
│     └─ app-state-tabs.test.ts
├─ design/
│  ├─ shared/
│  │  ├─ source-workspace.test.ts
│  │  ├─ shader-presets.test.ts
│  │  └─ canvas-math.test.ts
│  └─ server/
│     └─ lib/
│        ├─ import-design-files.test.ts
│        └─ design-export.test.ts
├─ calendar/
│  ├─ app/
│  │  ├─ lib/
│  │  │  ├─ event-form-utils.test.ts
│  │  │  └─ rsvp-status.test.ts
│  │  └─ components/calendar/
│  │     ├─ WeekView.test.tsx
│  │     └─ EventDetailPopover.test.tsx
│  └─ actions/
│     ├─ update-event.test.ts
│     └─ list-events.test.ts
├─ assets/
│  ├─ server/lib/
│  │  ├─ s3-upload-provider.test.ts
│  │  └─ image-processing.test.ts
│  └─ app/lib/
│     └─ picker-chat-handoff.test.ts
└─ brain/
   └─ evals/
      └─ slack-pilot-corpus.test.ts

Key test files include:

• templates/tasks/shared/navigation.test.ts – Navigation component verification
• templates/design/shared/canvas-math.test.ts – Geometric utility testing
• templates/calendar/app/components/calendar/WeekView.test.tsx – React week view component tests
• templates/calendar/actions/update-event.test.ts – Server-side event update logic
• templates/assets/server/lib/s3-upload-provider.test.ts – AWS S3 integration tests
• templates/brain/evals/slack-pilot-corpus.test.ts – LLM evaluation workflow tests

Representative Test Patterns

The repository employs consistent testing patterns across its TypeScript and React codebases, as demonstrated in these representative files.

Unit Testing Utilities

The navigation tests in templates/tasks/shared/navigation.test.ts demonstrate simple component verification:

import { render, screen } from '@testing-library/react';
import Navigation from '@/tasks/shared/navigation';

test('renders navigation links', () => {
  render(<Navigation />);
  expect(screen.getByText(/Home/)).toBeInTheDocument();
  expect(screen.getByText(/Settings/)).toBeInTheDocument();
});

React Component Testing

Component tests use .test.tsx extensions and verify UI behavior, as seen in templates/calendar/app/components/calendar/WeekView.test.tsx:

import { render } from '@testing-library/react';
import WeekView from '@/calendar/app/components/calendar/WeekView';

test('displays the correct number of days', () => {
  const { getAllByRole } = render(<WeekView weekStart={new Date('2024-01-01')} />);
  expect(getAllByRole('gridcell')).toHaveLength(7);
});

Server Action Testing

Server-side logic tests mock dependencies to isolate functionality, illustrated in templates/calendar/actions/update-event.test.ts:

import { updateEvent } from '@/calendar/actions/update-event';
import { mockDb } from '@/test-utils/mock-db';

test('updates an event correctly', async () => {
  const db = mockDb();
  await updateEvent(db, { id: 'e1', title: 'New Title' });
  const ev = await db.event.findUnique({ where: { id: 'e1' } });
  expect(ev?.title).toBe('New Title');
});

Summary

• Co-location strategy: Test files reside in templates/ next to source code, not in separate test directories
• Feature separation: Tests organize by functional areas (tasks, design, calendar, assets, brain) under templates/
• Naming convention: All tests use *.test.ts for logic or *.test.tsx for React components
• Structural parity: Test directories mirror the runtime folder hierarchy of the application
• Scalable pattern: New features simply add new sub-folders under templates/ following the same organizational rules

Frequently Asked Questions

Where are the test files located in Builder.io Agent Native?

Test files are co-located with source code inside the templates/ directory. Each feature area (tasks, design, calendar, etc.) has its own sub-folder containing both implementation and test files, ensuring tests sit beside the modules they verify rather than in a separate tests/ folder.

What naming convention do test files use?

All test files end with .test.ts for standard TypeScript files or .test.tsx for React components. This convention enables glob patterns like **/*.test.* to discover tests across the repository while clearly distinguishing logic tests from UI component tests containing JSX.

How does the test structure support feature development?

The feature-centric organization allows developers to drill into a specific feature folder (such as templates/calendar/) and immediately see all related unit, integration, and UI tests. This proximity reduces cognitive load when modifying code, as developers can view both implementation and verification in the same directory tree without switching contexts.

What testing framework does Builder.io Agent Native use?

Based on the code patterns visible in navigation.test.ts and WeekView.test.tsx, the repository uses Testing Library with Jest or a compatible runner. Tests import render and screen from @testing-library/react and utilize standard React testing patterns with expect assertions to verify component behavior and utility functions.

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