react-testing-conventions

name	react-testing-conventions
description	Testing conventions for React Native with TypeScript. Use this skill when writing tests, reviewing test code, or setting up test infrastructure. Covers unit tests, integration tests, component tests, test doubles (dummy, stub, spy, mock), builder pattern for fixtures, and the testing pyramid.

Testing Conventions

Testing conventions for React Native applications with TypeScript.

Stack: Bun test • React Native Testing Library • TypeScript

Core Principles

Testing Pyramid

Respect the testing pyramid — more unit tests, fewer integration tests, even fewer E2E tests:

        /\
       /  \      E2E (Maestro)
      /----\     Few, slow, expensive
     /      \
    /--------\   Integration
   /          \  Some, medium speed
  /------------\
 /              \ Unit (*.test.ts)
/________________\ Many, fast, cheap

FIRST Principles

Tests must be:

Principle	Description
Fast	Tests run quickly — milliseconds, not seconds
Independent	Tests don't depend on each other, can run in any order
Repeatable	Same result every time, no flakiness
Self-validating	Pass or fail, no manual inspection needed
Timely	Written at the same time as the code (or before with TDD)

File Organization

Naming

Type	Extension	Example
Unit test	.test.ts	Login.usecase.test.ts
E2E test (Maestro)	.yaml	login-flow.yaml

Colocation (Unit & Integration)

Test files live next to the files they test:

modules/authentication/core/usecases/
├── Login.usecase.ts
└── Login.usecase.test.ts

modules/authentication/ui/viewModels/
├── useLogin.viewModel.tsx
└── useLogin.viewModel.test.ts

modules/authentication/infrastructure/adapters/
├── AuthApi.adapter.ts
└── AuthApi.adapter.test.ts

E2E Tests (Maestro)

E2E tests live in a dedicated folder at project root:

tests/
├── flows/
│   ├── authentication/
│   │   ├── login-flow.yaml
│   │   └── logout-flow.yaml
│   └── events/
│       ├── create-event-flow.yaml
│       └── delete-event-flow.yaml
└── utils/
    └── common-steps.yaml

Test Anatomy

AAA Pattern

Every test follows Arrange, Act, Assert:

import { describe, it, expect } from "bun:test";

it("should return user when credentials are valid", async () => {
  // Arrange
  const authRepository = new AuthRepositoryStub();
  const useCase = new LoginUseCase(authRepository);
  const credentials = { email: "[e-mail]", password: "password123" };

  // Act
  const result = await useCase.execute(credentials);

  // Assert
  expect(result.success).toBe(true);
  expect(result.data.email).toBe("[e-mail]");
});

Test Naming

Pattern: should [expected behavior] when [condition]

// ✅ Good
it("should return failure when email is invalid");
it("should disable button when form is incomplete");
it("should invalidate queries when mutation succeeds");

// ❌ Bad
it("test login");
it("works");
it("handles error");

One logical assertion per test

// ✅ Good — one behavior tested
it("should return failure when password is too short", async () => {
  const result = await useCase.execute({ email: "[e-mail]", password: "123" });

  expect(result.success).toBe(false);
  expect(result.error.type).toBe("VALIDATION_ERROR");
});

// ❌ Bad — testing multiple unrelated behaviors
it("should validate all fields", async () => {
  const result1 = await useCase.execute({ email: "", password: "valid123" });
  expect(result1.success).toBe(false);

  const result2 = await useCase.execute({ email: "[e-mail]", password: "" });
  expect(result2.success).toBe(false);

  const result3 = await useCase.execute({
    email: "[e-mail]",
    password: "valid123",
  });
  expect(result3.success).toBe(true);
});

Test Doubles

When to use what

Test Double	Use Case	Layer
Dummy	Placeholder, never actually used	Core, UI
Stub	Returns predefined data	Core, UI
Spy	Records calls, verifies interactions	Infrastructure
Mock	Spy + predefined behavior	Infrastructure

Rule: Stub the Core, Mock the Infrastructure

// ✅ Core/UI tests — use stubs
// We test behavior, not implementation
const authRepository = new AuthRepositoryStub();
const useCase = new LoginUseCase(authRepository);

// ✅ Infrastructure tests — use spies/mocks
// We test the implementation itself
import { spyOn } from "bun:test";
const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(mockResponse);

Dummy

Never actually used, just satisfies the type:

class LoggerDummy implements Logger {
  log(_message: string): void {
    // Do nothing
  }
}

// Usage
const useCase = new SomeUseCase(realDependency, new LoggerDummy());

Stub

Returns predefined data:

class AuthRepositoryStub implements AuthRepository {
  private loginResult: Result<User, AuthError> = ok(userBuilder().build());

  withLoginSuccess(user: User): this {
    this.loginResult = ok(user);
    return this;
  }

  withLoginFailure(error: AuthError): this {
    this.loginResult = fail(error);
    return this;
  }

  async login(_params: LoginParams): Promise<Result<User, AuthError>> {
    return this.loginResult;
  }

  async logout(): Promise<Result<void, AuthError>> {
    return ok(undefined);
  }
}

// Usage
const stub = new AuthRepositoryStub().withLoginFailure({
  type: "INVALID_CREDENTIALS",
});

Spy / Mock (Infrastructure only)

import { describe, it, expect, spyOn } from "bun:test";

describe("AuthApiAdapter", () => {
  it("should call fetch with correct parameters", async () => {
    // Arrange
    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(
      new Response(JSON.stringify({ id: "1", email: "[e-mail]" }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      }),
    );

    const adapter = new AuthApiAdapter();

    // Act
    await adapter.login({ email: "[e-mail]", password: "password" });

    // Assert
    expect(fetchSpy).toHaveBeenCalledWith(
      "https://api.example.com/auth/login",
      expect.objectContaining({
        method: "POST",
        body: JSON.stringify({
          email: "[e-mail]",
          password: "password",
        }),
      }),
    );

    fetchSpy.mockRestore();
  });
});

Builder Pattern

Use builders to create test fixtures (entities, props, etc.):

Entity Builder

// modules/authentication/core/entities/User.builder.ts
import { User } from "./User.entity";

export const userBuilder = () => {
  const user: User = {
    id: "user-123",
    email: "[e-mail]",
    displayName: "Default User",
    createdAt: "2024-01-01T00:00:00Z",
  };

  const builder = {
    id: (id: string) => {
      user.id = id;
      return builder;
    },
    email: (email: string) => {
      user.email = email;
      return builder;
    },
    displayName: (displayName: string) => {
      user.displayName = displayName;
      return builder;
    },
    createdAt: (createdAt: string) => {
      user.createdAt = createdAt;
      return builder;
    },
    build: () => user,
  };

  return builder;
};

// Usage
const user = userBuilder()
  .email("[e-mail]")
  .displayName("Custom")
  .build();

Props Builder

// modules/events/ui/components/EventCard.props.builder.ts
import { mock } from "bun:test";
import { EventCardProps } from "./EventCard";

export const eventCardPropsBuilder = () => {
  const props: EventCardProps = {
    title: "Default Event",
    date: "2024-06-15T10:00:00Z",
    attendees: 10,
    onPress: mock(() => {}),
  };

  const builder = {
    title: (title: string) => {
      props.title = title;
      return builder;
    },
    date: (date: string) => {
      props.date = date;
      return builder;
    },
    attendees: (attendees: number) => {
      props.attendees = attendees;
      return builder;
    },
    onPress: (onPress: VoidFunction) => {
      props.onPress = onPress;
      return builder;
    },
    build: () => props,
  };

  return builder;
};

Builder naming

Type	File	Function
Entity	User.builder.ts	userBuilder()
Props	EventCard.props.builder.ts	eventCardPropsBuilder()
Params	LoginParams.builder.ts	loginParamsBuilder()

Testing Hooks

Custom renderHook

Use the custom renderHook that provides dependencies. See references/test-utils.md for the full implementation.

Usage

import { describe, it, expect } from "bun:test";
import { act } from "@testing-library/react-native";
import { renderHook } from "@shared/DI/ui/test-utils/renderHook";
import { useLoginViewModel } from "./useLogin.viewModel";

describe("useLoginViewModel", () => {
  it("should update state to success when login succeeds", async () => {
    // Arrange
    const authRepositoryStub = new AuthRepositoryStub().withLoginSuccess(
      userBuilder().build(),
    );

    // Act
    const { result } = renderHook(() => useLoginViewModel(), {
      dependencies: { authRepository: authRepositoryStub },
    });

    await act(async () => {
      await result.current.handlers.login("[e-mail]", "password123");
    });

    // Assert
    expect(result.current.state.status).toBe("success");
  });
});

Testing Components

Custom render

Use the custom render that provides dependencies. See references/test-utils.md for the full implementation.

Usage

import { describe, it, expect } from "bun:test";
import { screen, fireEvent } from "@testing-library/react-native";
import { render } from "@shared/DI/ui/test-utils/render";
import { LoginScreen } from "./LoginScreen";
import { TestIDs } from "@/constants/testIDs";

describe("LoginScreen", () => {
  it("should disable submit button when form is incomplete", () => {
    render(<LoginScreen />);

    const submitButton = screen.getByTestId(TestIDs.Login.submitButton);
    expect(submitButton.props.accessibilityState.disabled).toBe(true);
  });

  it("should call login when submit is pressed", async () => {
    // Arrange
    const authRepositoryStub = new AuthRepositoryStub();

    render(<LoginScreen />, {
      dependencies: { authRepository: authRepositoryStub },
    });

    // Act
    fireEvent.changeText(
      screen.getByTestId(TestIDs.Login.emailInput),
      "[e-mail]"
    );
    fireEvent.changeText(
      screen.getByTestId(TestIDs.Login.passwordInput),
      "password123"
    );
    fireEvent.press(screen.getByTestId(TestIDs.Login.submitButton));

    // Assert expected behavior
  });
});

Query priority

Prefer queries in this order:

1. getByRole — accessible queries
2. getByTestId — when role is not enough
3. getByText — for static text

// ✅ Good
screen.getByRole("button", { name: "Submit" });
screen.getByTestId(TestIDs.Login.submitButton);

// ❌ Avoid
screen.getByText("Submit"); // Fragile, breaks on text changes

Test Isolation

beforeEach / afterEach

import { describe, it, expect, beforeEach, afterEach } from "bun:test";

describe("useUserProfile", () => {
  let authRepositoryStub: AuthRepositoryStub;

  beforeEach(() => {
    authRepositoryStub = new AuthRepositoryStub();
  });

  afterEach(() => {
    // Cleanup if needed
  });

  it("should load user", async () => {
    // Test uses fresh authRepositoryStub
  });
});

Zustand Store Reset

Zustand stores must be reset between tests to ensure isolation. See references/test-utils.md for the full store template.

Testing with Zustand

Use setState directly to arrange state and reset:

import { describe, it, expect, beforeEach, afterEach } from "bun:test";
import { renderHook } from "@shared/DI/ui/test-utils/renderHook";
import { useProfileViewModel } from "./useProfile.viewModel";
import { createAuthStore } from "../stores/auth.store";

describe("useProfileViewModel", () => {
  let authStore: ReturnType<typeof createAuthStore>;

  beforeEach(() => {
    authStore = createAuthStore();
  });

  afterEach(() => {
    // Reset store — `true` replaces state entirely instead of merging
    authStore.setState({ user: null, isAuthenticated: false }, true);
  });

  it("should display user when authenticated", () => {
    // Arrange
    authStore.setState({
      user: userBuilder().displayName("John").build(),
      isAuthenticated: true,
    });

    const { result } = renderHook(() => useProfileViewModel(), {
      wrapper: ({ children }) => (
        <AuthStoreProvider store={authStore}>{children}</AuthStoreProvider>
      ),
    });

    // Assert
    expect(result.current.state.user?.displayName).toBe("John");
  });

  it("should show empty state when not authenticated", () => {
    // Store is fresh (created in beforeEach)
    const { result } = renderHook(() => useProfileViewModel(), {
      wrapper: ({ children }) => (
        <AuthStoreProvider store={authStore}>{children}</AuthStoreProvider>
      ),
    });

    expect(result.current.state.user).toBeNull();
  });
});

Anti-patterns

❌ Testing implementation details

// ❌ Bad — testing internal state
expect(component.state.isLoading).toBe(true);

// ✅ Good — testing behavior
expect(screen.getByTestId("loading-indicator")).toBeTruthy();

❌ Over-mocking

// ❌ Bad — mocking everything
mock.module("../hooks/useUser", () => ({ ... }));
mock.module("../hooks/useAuth", () => ({ ... }));
mock.module("../utils/format", () => ({ ... }));

// ✅ Good — only mock boundaries (adapters)
const authRepository = new AuthRepositoryStub();

❌ Tests without assertions

// ❌ Bad — no assertion, always passes
it("should render", () => {
  render(<Component />);
});

// ✅ Good — explicit assertion
it("should render title", () => {
  render(<Component />);
  expect(screen.getByText("Welcome")).toBeTruthy();
});

❌ Flaky tests

// ❌ Bad — timing dependent
await new Promise((r) => setTimeout(r, 1000));
expect(result).toBe(expected);

// ✅ Good — use waitFor
import { waitFor } from "@testing-library/react-native";
await waitFor(() => {
  expect(result).toBe(expected);
});

❌ Tests coupled to each other

// ❌ Bad — tests depend on shared state
let user: User;

it("should create user", () => {
  user = createUser();
  expect(user).toBeDefined();
});

it("should update user", () => {
  user.name = "New Name"; // Depends on previous test!
  expect(user.name).toBe("New Name");
});

// ✅ Good — independent tests
it("should create user", () => {
  const user = createUser();
  expect(user).toBeDefined();
});

it("should update user", () => {
  const user = createUser();
  user.name = "New Name";
  expect(user.name).toBe("New Name");
});

References

• references/test-utils.md — Full templates for renderHook, render, stores, builders, and stubs