Testing

BlaC provides first-party testing utilities so you can write fast, isolated tests for your cubits and the components that use them. The utilities live in two entry points:

• @blac/core/testing — registry isolation, state seeding, stubs, and method mocks
• @blac/react/testing — React component rendering with controlled bloc state

Both are tree-shakable and shipped as separate entry points, so they are never included in your production bundle.

Installation

The core testing utilities have no extra dependencies. Install your test runner of choice (Vitest is recommended):

pnpm

pnpm add -D vitest

npm

npm install -D vitest

yarn

yarn add -D vitest

For React component tests, you also need @testing-library/react:

pnpm

pnpm add -D @testing-library/react

npm

npm install -D @testing-library/react

yarn

yarn add -D @testing-library/react

Why registry isolation matters

BlaC stores every bloc instance in a single global registry. That is what lets any component call useBloc(CounterCubit) and reach the same instance without prop drilling. In tests, that same shared-by-default behavior works against you: a bloc created or mutated in one test is still in the registry when the next test runs, so tests leak state into each other and fail depending on execution order.

The mental model for testing BlaC is therefore simple: give every test its own registry. Once each test starts from an empty registry, the shared-instance model becomes a feature again — you seed exactly the instances a test needs and nothing carries over.

Every testing utility on this page’s child pages is built around that idea. The most common approach is blacTestSetup(), which swaps in a fresh registry before each test and restores the original after:

import { describe, it, expect } from 'vite-plus/test';
import { blacTestSetup } from '@blac/core/testing';
import { ensure } from '@blac/core';

blacTestSetup();

describe('CounterCubit', () => {
  it('does not see state from the previous test', () => {
    // Each test gets a completely fresh registry
    const counter = ensure(CounterCubit);
    expect(counter.state.count).toBe(0);
  });
});

For cubit-only tests (seeding, stubs, overrides, flush()), see Core Testing API. For component tests (renderWithBloc, renderWithRegistry), see React Testing.

Import test globals from vite-plus/test

This project runs tests through vite-plus, so describe/it/expect/vi are imported from vite-plus/test, not from vitest directly:

import { describe, it, expect, vi } from 'vite-plus/test';

Tests still run if you import bare globals, but linting fails. If you use a different runner, substitute its import — the BlaC helpers themselves are runner-agnostic.

Common mistakes

• Forgetting blacTestSetup() (or another isolation helper). Without it, a bloc mutated in one test survives into the next and you get order-dependent, flaky failures — exactly the problem isolation exists to prevent. See Core Testing API for the lower-level alternatives.
• Asserting on async state too early. State changes are flushed on a microtask, so a value set inside an async action may not be visible on the very next line. await flush() (or React Testing Library’s findBy* queries) before asserting. See System Events for the batching model.

See also

• Core Testing API — the full helper reference (blacTestSetup, stubs, overrides, seeding)
• React Testing API — rendering components with controlled bloc state
• Instance Management — the registry these helpers isolate
• Glossary — definitions for registry, stub, override, instance key