# Getting Started

## Installation

```bash
# 1. Install the library and its peer dependencies
npm install -D vitest-browser-three three vitest

# 2. Install Vitest Browser Mode packages (Playwright example)
npm install -D @vitest/browser @vitest/browser-playwright playwright

# 3. TypeScript users only, if you see a missing "three" declaration error
npm install -D @types/three
```

> If you already have Vitest Browser Mode configured, skip step 2.
>
> **Note:** Tested with Vitest 4.x, Playwright, and `three >=0.184.0`.

## Configure Vitest Browser Mode

Add browser mode configuration to `vite.config.ts`:

```ts
import { defineConfig } from "vitest/config";
import { playwright } from "@vitest/browser-playwright";

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      headless: true,
      provider: playwright({
        launchOptions: {
          args: [
            // Required: Chromium disables WebGPU by default in headless mode.
            "--enable-unsafe-webgpu",
            // Default to software rendering (works in restricted containers).
            // Set GPU_RENDER=hw to use the machine's real GPU via Vulkan.
            // Full reasoning for these flags: see the repo's vite.config.ts.
            ...(process.env.GPU_RENDER?.toLowerCase() === "hw"
              ? ["--use-angle=vulkan"]
              : ["--enable-features=Vulkan", "--use-angle=swiftshader"]),
          ],
          // Some dev containers export VK_LOADER_DRIVERS_SELECT=*nvidia*,
          // which hides non-NVIDIA Vulkan ICDs. Drop the restriction so
          // the loader can find any usable ICD.
          env: { ...process.env, VK_LOADER_DRIVERS_SELECT: "" },
        },
      }),
      instances: [{ browser: "chromium" }],
    },
  },
});
```

## Write Your First Test

```ts
import { it } from "vitest";
import { gpuTest } from "vitest-browser-three";
import { float, sin, vec3 } from "three/tsl";

it("vector math", async () => {
  await gpuTest("vector math", ({ eq, closeRel }) => {
    eq(float(2).add(3), float(5));
    closeRel(sin(float(Math.PI / 2)), 1, 1e-3);
    closeRel(vec3(1, 2, 3).mul(2), vec3(2, 4, 6));
  });
});
```

## Run Tests

```bash
# Use Vitest CLI directly
npx vitest

# Or if you defined a "test" script in package.json
npm test

# Hardware rendering (requires GPU with Vulkan)
# Default is software rendering via SwiftShader, which works in restricted
# containers and CI environments. Set GPU_RENDER=hw to use the machine's
# real GPU — but only if Vulkan is available.
GPU_RENDER=hw npx vitest
```

## Next Steps

- [Configuration](./configuration.md) — Backends and environment
- [`gpuTest`](./api/gpu-test.md) — Assertion API
- [`gpuFuzzTest`](./api/gpu-fuzz-test.md) — Fuzz testing
- [Best Practices](./best-practices.md) — Tolerances and strategies
- [Pure API](./pure.md) — Manual lifecycle
- [Troubleshooting](./troubleshooting.md) — Common issues