CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-testing-library--react-native

Simple and complete React Native testing utilities that encourage good testing practices

—

Pending
Overview
Eval results
Files

rendering.mddocs/

Component Rendering

Core rendering functionality for React Native components providing deep rendering capabilities, lifecycle management, and both synchronous and asynchronous rendering modes.

Capabilities

Render Function

Primary component rendering function that deeply renders React Native components using React Test Renderer.

/**
 * Renders test component deeply using React Test Renderer and exposes helpers
 * to assert on the output.
 * @param component - React element to render
 * @param options - Optional rendering configuration
 * @returns RenderResult with queries and utilities
 */
function render<T>(
  component: React.ReactElement<T>, 
  options?: RenderOptions
): RenderResult;

interface RenderOptions {
  /** React Component wrapper to render around the component */
  wrapper?: React.ComponentType<any>;
  /** Set to false to disable concurrent rendering (defaults to true) */
  concurrentRoot?: boolean;
  /** Function to create mock nodes for native elements */
  createNodeMock?: (element: React.ReactElement) => unknown;
  /** Validate strings are rendered within Text components */
  unstable_validateStringsRenderedWithinText?: boolean;
}

Usage Examples:

import React from "react";
import { View, Text } from "react-native";
import { render } from "@testing-library/react-native";

// Basic rendering
const MyComponent = () => (
  <View>
    <Text>Hello World</Text>
  </View>
);

test("renders component", () => {
  const { getByText } = render(<MyComponent />);
  expect(getByText("Hello World")).toBeOnTheScreen();
});

// With wrapper for providers
const ThemeProvider = ({ children }) => (
  <ThemeContext.Provider value={theme}>
    {children}
  </ThemeContext.Provider>
);

test("renders with theme provider", () => {
  const { getByText } = render(<MyComponent />, {
    wrapper: ThemeProvider
  });
});

// With createNodeMock for ref testing
test("renders with node mocks", () => {
  const mockScrollTo = jest.fn();
  const { getByTestId } = render(<ScrollViewComponent />, {
    createNodeMock: (element) => {
      if (element.type === "RCTScrollView") {
        return { scrollTo: mockScrollTo };
      }
      return null;
    }
  });
});

Render Result

Complete result object returned by render function containing queries, utilities, and component access.

interface RenderResult {
  /** Root element of the rendered component tree */
  root: ReactTestInstance;
  /** Legacy root access (deprecated) */
  UNSAFE_root: ReactTestInstance;
  
  /** Debug the rendered component tree */
  debug: DebugFunction;
  /** Re-render component with new props */
  rerender: (element: React.ReactElement) => void;
  /** Unmount the component */
  unmount: () => void;
  /** Get JSON representation of the rendered tree */
  toJSON: () => ReactTestRendererJSON | null;
  
  // Text queries
  getByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance;
  getAllByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance[];
  queryByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance | null;
  queryAllByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance[];
  findByText: (text: string | RegExp, options?: TextMatchOptions & WaitForOptions) => Promise<ReactTestInstance>;
  findAllByText: (text: string | RegExp, options?: TextMatchOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
  
  // TestID queries
  getByTestId: (testId: string | RegExp, options?: TestIdOptions) => ReactTestInstance;
  getAllByTestId: (testId: string | RegExp, options?: TestIdOptions) => ReactTestInstance[];
  queryByTestId: (testId: string | RegExp, options?: TestIdOptions) => ReactTestInstance | null;
  queryAllByTestId: (testId: string | RegExp, options?: TestIdOptions) => ReactTestInstance[];
  findByTestId: (testId: string | RegExp, options?: TestIdOptions & WaitForOptions) => Promise<ReactTestInstance>;
  findAllByTestId: (testId: string | RegExp, options?: TestIdOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
  
  // Role queries
  getByRole: (role: string, options?: RoleOptions) => ReactTestInstance;
  getAllByRole: (role: string, options?: RoleOptions) => ReactTestInstance[];
  queryByRole: (role: string, options?: RoleOptions) => ReactTestInstance | null;
  queryAllByRole: (role: string, options?: RoleOptions) => ReactTestInstance[];
  findByRole: (role: string, options?: RoleOptions & WaitForOptions) => Promise<ReactTestInstance>;
  findAllByRole: (role: string, options?: RoleOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
  
  // Label text queries
  getByLabelText: (text: string | RegExp, options?: LabelTextOptions) => ReactTestInstance;
  getAllByLabelText: (text: string | RegExp, options?: LabelTextOptions) => ReactTestInstance[];
  queryByLabelText: (text: string | RegExp, options?: LabelTextOptions) => ReactTestInstance | null;
  queryAllByLabelText: (text: string | RegExp, options?: LabelTextOptions) => ReactTestInstance[];
  findByLabelText: (text: string | RegExp, options?: LabelTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
  findAllByLabelText: (text: string | RegExp, options?: LabelTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
  
  // Hint text queries  
  getByHintText: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance;
  getAllByHintText: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
  queryByHintText: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance | null;
  queryAllByHintText: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
  findByHintText: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
  findAllByHintText: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
  
  // Accessibility hint aliases
  getByA11yHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance;
  getAllByA11yHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
  queryByA11yHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance | null;
  queryAllByA11yHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
  findByA11yHint: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
  findAllByA11yHint: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
  
  getByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance;
  getAllByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
  queryByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance | null;
  queryAllByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
  findByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
  findAllByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
  
  // Placeholder text queries
  getByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions) => ReactTestInstance;
  getAllByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions) => ReactTestInstance[];
  queryByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions) => ReactTestInstance | null;
  queryAllByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions) => ReactTestInstance[];
  findByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
  findAllByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
  
  // Display value queries
  getByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions) => ReactTestInstance;
  getAllByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions) => ReactTestInstance[];
  queryByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions) => ReactTestInstance | null;
  queryAllByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions) => ReactTestInstance[];
  findByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions & WaitForOptions) => Promise<ReactTestInstance>;
  findAllByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
  
  // Unsafe queries (advanced usage)
  UNSAFE_getByType: (type: React.ComponentType | string, options?: TypeOptions) => ReactTestInstance;
  UNSAFE_getAllByType: (type: React.ComponentType | string, options?: TypeOptions) => ReactTestInstance[];
  UNSAFE_queryByType: (type: React.ComponentType | string, options?: TypeOptions) => ReactTestInstance | null;
  UNSAFE_queryAllByType: (type: React.ComponentType | string, options?: TypeOptions) => ReactTestInstance[];
  
  UNSAFE_getByProps: (props: object, options?: PropsOptions) => ReactTestInstance;
  UNSAFE_getAllByProps: (props: object, options?: PropsOptions) => ReactTestInstance[];
  UNSAFE_queryByProps: (props: object, options?: PropsOptions) => ReactTestInstance | null;
  UNSAFE_queryAllByProps: (props: object, options?: PropsOptions) => ReactTestInstance[];
}

Async Rendering

Asynchronous rendering function for components that require async setup or concurrent rendering.

/**
 * Async version of render for concurrent rendering scenarios
 * @param component - React element to render
 * @param options - Optional async rendering configuration
 * @returns Promise resolving to RenderAsyncResult
 */
function renderAsync<T>(
  component: React.ReactElement<T>,
  options?: RenderAsyncOptions
): Promise<RenderAsyncResult>;

interface RenderAsyncOptions {
  wrapper?: React.ComponentType<any>;
  concurrentRoot?: boolean;
  createNodeMock?: (element: React.ReactElement) => unknown;
  unstable_validateStringsRenderedWithinText?: boolean;
}

interface RenderAsyncResult {
  // Same as RenderResult but with async methods
  root: ReactTestInstance;
  UNSAFE_root: ReactTestInstance;
  debug: DebugFunction;
  rerenderAsync: (element: React.ReactElement) => Promise<void>;
  updateAsync: (element: React.ReactElement) => Promise<void>;
  unmountAsync: () => Promise<void>;
  toJSON: () => ReactTestRendererJSON | null;
  
  // All the same query methods as RenderResult
  // ... (queries omitted for brevity)
}

Usage Examples:

import { renderAsync } from "@testing-library/react-native";

test("async component rendering", async () => {
  const AsyncComponent = () => {
    const [data, setData] = useState(null);
    
    useEffect(() => {
      fetchData().then(setData);
    }, []);
    
    return data ? <Text>{data.message}</Text> : <Text>Loading...</Text>;
  };

  const { findByText } = await renderAsync(<AsyncComponent />);
  
  // Wait for async data to load
  await expect(findByText("Loaded message")).resolves.toBeOnTheScreen();
});

Debug Function

Utility function for debugging rendered component trees during test development.

/**
 * Debug function for inspecting rendered component tree
 * @param element - Optional element to debug (defaults to entire tree)
 * @param maxLength - Maximum length of output
 * @param options - Debug formatting options  
 */
interface DebugFunction {
  (element?: ReactTestInstance, maxLength?: number, options?: DebugOptions): void;
}

interface DebugOptions {
  mapProps?: (props: Record<string, any>) => Record<string, any>;
  maxLength?: number;
}

Usage Examples:

test("debug component tree", () => {
  const { debug, getByTestId } = render(<MyComponent />);
  
  // Debug entire tree
  debug();
  
  // Debug specific element
  const button = getByTestId("submit-button");
  debug(button);
  
  // Debug with options
  debug(button, 1000, { 
    mapProps: (props) => ({ ...props, onPress: "[Function]" })
  });
});

Screen Global API

Global screen object providing access to queries without destructuring render result.

/**
 * Global screen object with all query methods
 * Available after calling render()
 */
declare const screen: {
  // All the same methods as RenderResult
  debug: DebugFunction;
  root: ReactTestInstance;
  UNSAFE_root: ReactTestInstance;
  
  // All query methods (getBy*, getAllBy*, queryBy*, queryAllBy*, findBy*, findAllBy*)
  getByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance;
  // ... (all other query methods)
};

Usage Examples:

import { render, screen } from "@testing-library/react-native";

test("using screen API", () => {
  render(<MyComponent />);
  
  // Use screen instead of destructuring
  const button = screen.getByText("Press me");
  const input = screen.getByPlaceholderText("Enter name");
  
  // Debug using screen
  screen.debug();
});

Cleanup and Lifecycle

Cleanup functions for managing component lifecycle and test isolation.

/**
 * Clean up rendered components synchronously
 */
function cleanup(): void;

/**
 * Clean up rendered components asynchronously
 * @returns Promise that resolves when cleanup is complete
 */
function cleanupAsync(): Promise<void>;

Usage Examples:

import { render, cleanup, cleanupAsync } from "@testing-library/react-native/pure";

afterEach(() => {
  cleanup(); // or cleanupAsync() for async cleanup
});

// Manual cleanup in specific tests
test("manual cleanup", async () => {
  render(<MyComponent />);
  // ... test logic
  
  await cleanupAsync();
  
  render(<AnotherComponent />);
  // ... more test logic
});

Install with Tessl CLI

npx tessl i tessl/npm-testing-library--react-native

docs

async-testing.md

configuration.md

hooks.md

index.md

interactions.md

matchers.md

queries.md

rendering.md

tile.json