alepha@docs:~/docs/guides/testing$
cat 2-react-tests.md
2 min read
Last commit:

#React Tests

Alepha provides testing utilities for React components through alepha/react/testing. Browser tests run in jsdom via Vitest and use @testing-library/react under the hood.

#File Naming Convention

Browser test files must use the .browser.spec.ts or .browser.spec.tsx extension. Vitest automatically runs these files in the jsdom environment.

bash 
src/
  web/
    components/
      LoginForm.tsx
      LoginForm.browser.spec.tsx   # Runs in jsdom

#Utilities

The alepha/react/testing module exports:

Function Purpose
renderWithAlepha(element, options?) Async render with Alepha context (auto-starts the instance)
renderWithAlephaSync(element, options?) Sync render (autoStart defaults to false)
fillForm(screen, formId, values) Fill form fields by test ID ({formId}-{fieldName})
fillField(screen, testId, value) Fill a single field by its test ID
submitForm(screen, options?) Click the submit button (default text: "Submit")
resetForm(screen, buttonText?) Click the reset button (default text: "Reset")
waitForFormSubmit(alepha, formId) Wait for the form:submit:end event
toggleSwitch(screen, role?, name?) Toggle a switch or checkbox element
setupJsdomMocks() Mock matchMedia, ResizeObserver, IntersectionObserver, scrollTo, getComputedStyle

#Basic Rendering

typescript 
1import { renderWithAlepha, setupJsdomMocks } from "alepha/react/testing";2 3beforeAll(() => setupJsdomMocks());4 5test("should render greeting", async () => {6  const { getByText, alepha } = await renderWithAlepha(<Greeting name="Alice" />);7 8  expect(getByText("Hello, Alice")).toBeDefined();9});

renderWithAlepha creates an Alepha instance, starts it, and wraps the component in AlephaContext.Provider. It returns the standard @testing-library/react render result plus the alepha instance.

#Custom Alepha Configuration

Pass a pre-configured Alepha instance to swap services or providers:

typescript 
1import { renderWithAlepha } from "alepha/react/testing";2 3test("should render with mocked service", async () => {4  const alepha = Alepha.create().with({ provide: UserService, use: FakeUserService });5 6  const { getByText } = await renderWithAlepha(<UserProfile />, { alepha });7 8  expect(getByText("Fake User")).toBeDefined();9});

#Wrapper Components

Use the wrapper option to add UI framework providers (theme, i18n):

typescript 
 1import { renderWithAlepha } from "alepha/react/testing"; 2import { ThemeProvider } from "my-ui-library"; 3  4test("should render themed component", async () => { 5  const { getByRole } = await renderWithAlepha( 6    <Button>Click me</Button>, 7    { wrapper: ThemeProvider }, 8  ); 9 10  expect(getByRole("button")).toBeDefined();11});

#Form Testing

Form helpers find inputs by test IDs constructed as {formId}-{fieldName}.

typescript 
 1import { 2  renderWithAlepha, 3  fillForm, 4  submitForm, 5  waitForFormSubmit, 6  setupJsdomMocks, 7} from "alepha/react/testing"; 8  9beforeAll(() => setupJsdomMocks());10 11test("should submit login form", async () => {12  const { screen, alepha } = await renderWithAlepha(<LoginForm />);13 14  await fillForm(screen, "login-form", {15    email: "[email protected]",16    password: "secret123",17  });18 19  await submitForm(screen, { submitButtonText: "Login" });20 21  // Optionally wait for submission to complete22  await waitForFormSubmit(alepha, "login-form");23});

#Nested Fields

For nested form fields, use dot notation in the field name:

typescript 
1await fillForm(screen, "address-form", {2  "address.city": "New York",3  "address.zip": "10001",4});

#Checkboxes and Switches

fillForm automatically detects checkbox and switch inputs. Pass true or false as the value:

typescript 
1await fillForm(screen, "settings-form", {2  notifications: true,3  darkMode: false,4});

You can also toggle switches directly:

typescript 
1import { toggleSwitch } from "alepha/react/testing";2 3await toggleSwitch(screen, "switch", "Enable notifications");

#jsdom Mocks

Call setupJsdomMocks() in beforeAll to mock browser APIs that jsdom does not implement. This is required for components that use responsive styles, scroll behavior, or intersection observers.

typescript 
1import { setupJsdomMocks } from "alepha/react/testing";2 3beforeAll(() => {4  setupJsdomMocks();5});

Mocked APIs:

  • window.matchMedia
  • window.ResizeObserver
  • window.IntersectionObserver
  • window.scrollTo
  • window.getComputedStyle