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

> Discover how Builder.io Agent Native organizes tests. Learn about co-location within templates and the feature-centric structure placing test files alongside source code for efficient development.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-07-18

---

**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`](https://github.com/BuilderIO/agent-native/blob/main/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:

```text
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`](https://github.com/BuilderIO/agent-native/blob/main/templates/tasks/shared/navigation.test.ts) – Navigation component verification
- [`templates/design/shared/canvas-math.test.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/design/shared/canvas-math.test.ts) – Geometric utility testing
- [`templates/calendar/app/components/calendar/WeekView.test.tsx`](https://github.com/BuilderIO/agent-native/blob/main/templates/calendar/app/components/calendar/WeekView.test.tsx) – React week view component tests
- [`templates/calendar/actions/update-event.test.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/calendar/actions/update-event.test.ts) – Server-side event update logic
- [`templates/assets/server/lib/s3-upload-provider.test.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/assets/server/lib/s3-upload-provider.test.ts) – AWS S3 integration tests
- [`templates/brain/evals/slack-pilot-corpus.test.ts`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/templates/tasks/shared/navigation.test.ts) demonstrate simple component verification:

```typescript
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`](https://github.com/BuilderIO/agent-native/blob/main/.test.tsx) extensions and verify UI behavior, as seen in [`templates/calendar/app/components/calendar/WeekView.test.tsx`](https://github.com/BuilderIO/agent-native/blob/main/templates/calendar/app/components/calendar/WeekView.test.tsx):

```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`](https://github.com/BuilderIO/agent-native/blob/main/templates/calendar/actions/update-event.test.ts):

```typescript
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`](https://github.com/BuilderIO/agent-native/blob/main/.test.ts) for standard TypeScript files or [`.test.tsx`](https://github.com/BuilderIO/agent-native/blob/main/.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`](https://github.com/BuilderIO/agent-native/blob/main/navigation.test.ts) and [`WeekView.test.tsx`](https://github.com/BuilderIO/agent-native/blob/main/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.