# Role of the Tests Directory in Wand Enhancer: Co-Located Testing Architecture

> Discover the role of the tests directory in Wand Enhancer's co-located testing architecture. Learn how *.test.ts and *.test.tsx files ensure unit, protocol, and UI verification for the Electron interface.

- Repository: [k1tbyte/Wand-Enhancer](https://github.com/k1tbyte/Wand-Enhancer)
- Tags: internals
- Published: 2026-07-13

---

**The tests directory in Wand Enhancer refers to the co-located test suite embedded within the web-panel source code, where `*.test.ts` and `*.test.tsx` files provide unit verification, protocol validation, and UI guarantees for the Electron-based remote interface.**

The Wand Enhancer repository (k1tbyte/Wand-Enhancer) does not rely on a single monolithic `tests/` folder at the project root. Instead, it implements a distributed testing strategy where test files live alongside the modules they verify within the `web-panel` directory, providing immediate feedback on the integrity of the Electron bridge and Preact-based UI components.

## Distributed Test Architecture

Rather than isolating tests in a top-level directory, the Wand Enhancer project embeds its automated test suite directly within the **web-panel** source tree. Test files using the [`.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/.test.ts) and [`.test.tsx`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/.test.tsx) extensions reside in the same directories as their implementation counterparts under `web-panel/src/**` and `web-panel/bridge/**`. This co-location pattern ensures that developers can instantly identify the intended use cases and edge-case handling for each module, serving as living documentation for future contributors.

## Core Testing Responsibilities

The test suite serves several architectural purposes that guarantee the correctness of the web-panel’s logic, data contracts, and UI rendering while keeping the core WPF patcher untouched.

### Unit Verification

Each component, utility, or service has a corresponding test that isolates its public API and checks expected behavior. For example, [`web-panel/src/trainer/presets/preset-storage.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/src/trainer/presets/preset-storage.test.ts) validates the local-storage logic for trainer presets using **Vitest**:

```typescript
import { beforeEach, describe, expect, it } from 'vitest';
import { savePreset, loadPreset } from '../presets/preset-storage';

describe('Preset storage', () => {
  beforeEach(() => localStorage.clear());

  it('stores and retrieves a preset correctly', () => {
    const preset = { id: 'abc', values: { health: 100 } };
    savePreset(preset);
    expect(loadPreset('abc')).toEqual(preset);
  });
});

```

### Contract and Protocol Safety

Tests ensure that the JSON-based Web-Panel protocol matches the schema defined in [`protocol/web-contract.json`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/protocol/web-contract.json). The file [`web-panel/protocol/validation.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/protocol/validation.test.ts) exercises message validation logic to prevent runtime protocol mismatches:

```typescript
import { validateMessage } from '../../protocol/validation';

describe('Protocol validation', () => {
  it('rejects unknown message types', () => {
    const msg = { type: 'unknown', payload: {} };
    expect(() => validateMessage(msg)).toThrow();
  });
});

```

### Bridge Integrity

The bridge layer (TypeScript code that communicates between the Electron main process and the renderer) is exercised by tests like [`web-panel/bridge/src/protocol-router.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/protocol-router.test.ts) and [`web-panel/bridge/src/normalizers/trainer.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/normalizers/trainer.test.ts). This catches regressions in IPC routing and data transformation before they reach production builds.

### Renderer UI Guarantees

UI components are exercised with the lightweight Preact rendering library and the Testing Library (`@testing-library/preact`). Tests like [`web-panel/src/app/ui/session-states.test.tsx`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/src/app/ui/session-states.test.tsx) verify UI state transitions without loading the full Electron app:

```tsx
import { render, screen } from '@testing-library/preact';
import SessionStates from './session-states';

test('shows "Connecting" when status is CONNECTING', () => {
  render(<SessionStates status="CONNECTING" />);
  expect(screen.getByText('Connecting…')).toBeInTheDocument();
});

```

## Continuous Integration Safeguard

The test suite acts as a merge-blocking gate in the project's continuous integration pipeline. According to the repository configuration, the `npm`/`pnpm` script `test` executes `pnpm build:bridge && vitest run` on every commit. Failing tests block merges, ensuring that new changes do not break existing functionality in the web-panel bridge or UI components.

## Key Test Files and Their Functions

The following files illustrate how the repository’s test suite is tightly integrated with the core web-panel code:

- **[`web-panel/src/trainer/presets/preset-storage.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/src/trainer/presets/preset-storage.test.ts)**: Unit tests for preset-storage logic and localStorage interactions.
- **[`web-panel/src/trainer/model/categories.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/src/trainer/model/categories.test.ts)**: Tests for cheat-category modeling and data structures.
- **[`web-panel/src/shared/storage.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/src/shared/storage.test.ts)**: Verifies the shared storage helpers used throughout the panel.
- **[`web-panel/src/remote-session/remote-session.reducer.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/src/remote-session/remote-session.reducer.test.ts)**: Tests the Redux-style reducer that tracks remote session state.
- **[`web-panel/src/library/model/games.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/src/library/model/games.test.ts)**: Ensures the game-library model parses and filters correctly.
- **[`web-panel/src/app/ui/session-states.test.tsx`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/src/app/ui/session-states.test.tsx)**: UI component test for session-state rendering with Preact.
- **[`web-panel/protocol/validation.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/protocol/validation.test.ts)**: Validates protocol messages against the web-contract schema.
- **[`web-panel/bridge/src/protocol-router.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/protocol-router.test.ts)**: Tests the bridge’s IPC routing logic between main and renderer processes.
- **[`web-panel/bridge/src/normalizers/trainer.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/normalizers/trainer.test.ts)**: Checks data normalization for trainer objects crossing the Electron bridge.

## Summary

- The Wand Enhancer **tests directory** is not a single folder but a distributed collection of `*.test.ts` and `*.test.tsx` files co-located with source code under `web-panel/`.
- **Unit tests** verify isolated logic like preset storage and category models using Vitest.
- **Protocol tests** enforce contract safety against [`web-contract.json`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-contract.json) to prevent IPC communication errors.
- **Bridge tests** ensure data integrity in the Electron main-to-renderer communication layer.
- **UI tests** leverage Preact and Testing Library to validate component rendering without launching the full Electron application.
- The `test` script (`pnpm build:bridge && vitest run`) runs on every commit to block regressions before merge.

## Frequently Asked Questions

### Where are the test files located in the Wand Enhancer repository?

The test files are co-located with the source code they verify within the `web-panel` directory, following the pattern `*.test.ts` for utilities and `*.test.tsx` for Preact components. You will find them alongside implementation files in paths like `web-panel/src/trainer/presets/` and `web-panel/bridge/src/`.

### What testing framework does Wand Enhancer use?

The project uses **Vitest** for the test runner and assertion library, paired with **@testing-library/preact** for UI component testing. This combination provides fast, lightweight verification suitable for the Electron bridge environment without requiring a full browser instance.

### Why doesn't Wand Enhancer have a top-level tests directory?

The repository intentionally avoids a monolithic `tests/` folder to keep tests adjacent to the code they exercise. This co-location strategy improves discoverability, serves as living documentation, and ensures that changes to source files are accompanied by corresponding test updates in the same pull request.

### How do the tests prevent breaking changes in the Electron bridge?

Tests like [`bridge/src/protocol-router.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/bridge/src/protocol-router.test.ts) and [`bridge/src/normalizers/trainer.test.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/bridge/src/normalizers/trainer.test.ts) validate IPC routing logic and data normalization. The CI pipeline runs `vitest run` via the `test` script on every commit, blocking merges that would introduce regressions in the communication layer between the Electron main process and the renderer.