volt

# JavaScript and TypeScript Testing

Volt can register JavaScript and TypeScript test files as ordinary ExUnit tests. You still run one command:

```bash
mix test
```

The JS/TS runner is Volt-native: test files are bundled with OXC, executed in QuickBEAM, and reported through ExUnit. There is no separate `mix volt.test` command and no Vitest/Node process to manage.

## Setup

Add the Volt test installer to `test/test_helper.exs` after `ExUnit.start/1`:

```elixir
ExUnit.start(exclude: [:integration])

Volt.Test.ExUnit.install()
```

By default, Volt looks under `assets/` for:

```text
**/*.{test,spec}.{js,ts,jsx,tsx}
```

Configure discovery with `config :volt, :test`:

```elixir
config :volt, :test,
  root: "assets",
  include: ["**/*.{test,spec}.{js,ts,jsx,tsx}"],
  exclude: ["vendor/**", "node_modules/**"],
  timeout: 30_000
```

You can also pass options directly from `test/test_helper.exs`, which is useful for package dogfood tests or custom fixture roots:

```elixir
Volt.Test.ExUnit.install(
  root: "test/volt/test/fixtures",
  include: ["core_api.test.ts"]
)
```

Profile-specific configuration follows the rest of Volt:

```elixir
config :volt, :my_app_web,
  test: [root: "apps/my_app_web/assets", include: ["**/*.test.ts"]]
```

Then install that profile:

```elixir
Volt.Test.ExUnit.install(profile: :my_app_web)
```

## Writing tests

Import the Vitest-like API from `volt:test`:

```ts
import { describe, test, expect, beforeEach, afterEach } from 'volt:test'
import { add } from './math'

describe('add', () => {
  beforeEach(() => {
    // setup
  })

  test('adds numbers', () => {
    expect(add(1, 2)).toBe(3)
  })
})
```

Async tests can return promises or use `async` functions:

```ts
test('loads data', async () => {
  const value = await Promise.resolve(42)
  expect(value).toBe(42)
})
```

Relative imports are bundled before execution:

```ts
import { frameworkName } from './support'

test('uses helper module', () => {
  expect(frameworkName).toContain('volt')
})
```

## Test and suite modifiers

Skip or mark tests as TODO:

```ts
test.skip('not ready yet', () => {
  throw new Error('will not run')
})

test.todo('add coverage for browser behavior')
```

Suites support the same modifiers:

```ts
describe.skip('external service', () => {
  test('calls service', () => {
    // skipped
  })
})

describe.todo('future behavior', () => {
  test('documents planned coverage')
})
```

You can also skip dynamically from the test context:

```ts
test('platform-specific behavior', ({ skip }) => {
  skip(!navigator.userAgent.includes('Firefox'), 'Firefox only')
  expect(true).toBe(true)
})
```

## Parameterized tests

Use `test.each` for table-driven tests:

```ts
test.each([
  [1, 2, 3],
  [2, 3, 5]
])('adds %d + %d = %d', (left, right, total) => {
  expect(Number(left) + Number(right)).toBe(total)
})
```

Use `describe.each` to repeat a suite for multiple values:

```ts
describe.each(['en', 'fr'])('locale %s', (locale) => {
  test('has a locale code', () => {
    expect(String(locale)).toHaveLength(2)
  })
})
```

Supported placeholders in each-test names are `%s`, `%d`, `%i`, `%f`, `%j`, and `%o`.

## Matchers

Volt includes a small core matcher set:

```ts
expect(value).toBe(expected)
expect(value).toEqual(expected)
expect(value).toContain(expected)
expect(value).toMatch(/pattern/)
expect(value).toHaveLength(3)
expect(value).toHaveProperty('nested.value', 42)
expect(value).toBeDefined()
expect(value).toBeUndefined()
expect(value).toBeTruthy()
expect(value).toBeFalsy()
expect(value).toBeNull()
expect(value).toBeNaN()
expect(value).toBeCloseTo(0.3, 5)
expect(value).toBeGreaterThan(1)
expect(value).toBeGreaterThanOrEqual(1)
expect(value).toBeLessThan(10)
expect(value).toBeLessThanOrEqual(10)
expect(fn).toThrow('message')
```

All matchers support `.not`:

```ts
expect('volt').not.toContain('vite')
expect(1 + 1).not.toBe(3)
```

## Browser tests

Use `browser: true` when tests need real browser globals such as `window`, `document`, layout APIs, or DOM events:

```elixir
Volt.Test.ExUnit.install(
  root: "test/browser",
  include: ["**/*.browser.test.ts"],
  browser: true
)
```

Browser tests still use the same `volt:test` API and still register one ExUnit test per JS `test(...)`. They are best suited for browser-owned runtime behavior such as DOM helpers, client preload logic, and other code that needs real browser globals. Keep Elixir-owned behavior such as manifests, Plug responses, cache state, and build output in ordinary ExUnit tests.

```ts
import { test, expect } from 'volt:test'

test('updates the DOM', () => {
  document.body.innerHTML = '<button id="save">Save</button>'
  expect(document.querySelector('#save')?.textContent).toBe('Save')
})
```

Volt runs these tests through PlaywrightEx. Install Playwright for local browser execution:

```bash
npm install --save-dev playwright
npx playwright install chromium
```

By default Volt uses `node_modules/.bin/playwright` when present, otherwise `playwright` from `PATH`. Pass PlaywrightEx supervisor options with `playwright: [...]` if your executable lives elsewhere.

## ExUnit integration

Each collected JS/TS `test(...)` becomes an ExUnit test. That means normal ExUnit filtering, formatters, failures, and CI behavior continue to work.

Volt adds useful tags:

- `:js` — JS/TS test generated by Volt
- `:volt_file` — source test file path
- `:volt_test_id` — collected test id inside the file
- `:volt_tags` — tags passed from JS test options

For example:

```ts
test('slow calculation', { tags: ['slow'] }, () => {
  expect(1 + 1).toBe(2)
})
```

Skipped and TODO tests are registered as skipped ExUnit tests, so they are visible in normal ExUnit output.

## ExUnit fixture sigils

When an Elixir test needs readable JS/TS input, import `Volt.Test.Sigils`:

```elixir
import Volt.Test.Sigils

source = ~TS"""
export const answer: number = 42
"""
```

Use the `v` modifier to parse-check a snippet with OXC:

```elixir
source = ~TS"export const value: string = 'ok'"v
```

Available sigils: `~JS`, `~TS`, `~JSX`, `~TSX`, `~CSS`, and `~HTML`.

## Current scope

The QuickBEAM runner is intended for fast JS/TS unit tests. The browser runner is intended for tests that genuinely need a browser environment. Higher-level Phoenix end-to-end flows can still use PlaywrightEx or Phoenix-oriented browser-test helpers alongside Volt's JS test runner.