@rstest/browser-react 0.7.9

package/README.md

@@ -0,0 +1,269 @@
+# @rstest/browser-react
+
+React component testing utilities for [Rstest](https://rstest.dev) browser mode.
+
+This package provides `render` and `renderHook` functions for testing React components in a real browser environment. Tests run in an actual browser rather than a simulated DOM like jsdom.
+
+For a complete working example, see the [browser example](../../examples/browser-react) in the Rstest repository.
+
+## Installation
+
+```bash
+npm install @rstest/browser-react
+# or
+pnpm add @rstest/browser-react
+```
+
+For DOM queries and user interactions, also install:
+
+```bash
+npm install @testing-library/dom @testing-library/user-event
+# or
+pnpm install @testing-library/dom @testing-library/user-event
+```
+
+## Usage
+
+### Basic component testing
+
+Use the `render` function to mount a React component into the DOM. This is the foundation for all component tests:
+
+```tsx
+import { render } from '@rstest/browser-react';
+import { getByRole, getByText } from '@testing-library/dom';
+import { expect, test } from '@rstest/core';
+
+test('renders button with text', async () => {
+  const { container } = await render(<button>Click me</button>);
+
+  expect(getByRole(container, 'button')).toBeTruthy();
+  expect(getByText(container, 'Click me')).toBeTruthy();
+});
+```
+
+### Testing with providers
+
+When your component depends on React Context (e.g., theme, auth, store), use the `wrapper` option to wrap it with the necessary providers:
+
+```tsx
+import { render } from '@rstest/browser-react';
+
+const Wrapper = ({ children }: { children: React.ReactNode }) => (
+  <ThemeProvider theme="dark">{children}</ThemeProvider>
+);
+
+test('renders with theme context', async () => {
+  const { container } = await render(<MyComponent />, { wrapper: Wrapper });
+  // ...assertions
+});
+```
+
+### User interactions
+
+Simulate realistic user interactions (clicks, typing, etc.) using `@testing-library/user-event`:
+
+```tsx
+import { render } from '@rstest/browser-react';
+import { getByRole, getByText } from '@testing-library/dom';
+import userEvent from '@testing-library/user-event';
+import { expect, test } from '@rstest/core';
+
+test('increments counter on click', async () => {
+  const { container } = await render(<Counter />);
+  const button = getByRole(container, 'button');
+
+  await userEvent.click(button);
+
+  expect(getByText(container, 'Count: 1')).toBeTruthy();
+});
+```
+
+### Testing hooks
+
+Use `renderHook` to test custom hooks in isolation, without needing to create a wrapper component. The returned `act` function ensures state updates are properly flushed:
+
+```tsx
+import { renderHook } from '@rstest/browser-react';
+import { useState } from 'react';
+import { expect, test } from '@rstest/core';
+
+test('useState updates value', async () => {
+  const { result, act } = await renderHook(() => useState(0));
+
+  expect(result.current[0]).toBe(0);
+
+  await act(() => {
+    result.current[1](1);
+  });
+
+  expect(result.current[0]).toBe(1);
+});
+```
+
+### Testing hooks with props
+
+When your hook depends on props, use `initialProps` and `rerender` to test how the hook responds to prop changes:
+
+```tsx
+import { renderHook } from '@rstest/browser-react';
+import { useMemo } from 'react';
+import { expect, test } from '@rstest/core';
+
+test('hook reacts to prop changes', async () => {
+  const { result, rerender } = await renderHook(
+    (props) => useMemo(() => (props?.value ?? 0) * 2, [props?.value]),
+    { initialProps: { value: 5 } },
+  );
+
+  expect(result.current).toBe(10);
+
+  await rerender({ value: 10 });
+
+  expect(result.current).toBe(20);
+});
+```
+
+### React strict mode
+
+To enable React Strict Mode for catching potential issues, use the `configure` function:
+
+```tsx
+import { configure } from '@rstest/browser-react';
+
+configure({ reactStrictMode: true });
+```
+
+### Pure entry
+
+The `/pure` entry (`@rstest/browser-react/pure`) exports the same API but without automatic cleanup registration. Use it when you need manual control over cleanup timing:
+
+```tsx
+import { cleanup, render } from '@rstest/browser-react/pure';
+import { afterEach } from '@rstest/core';
+
+afterEach(async () => {
+  await cleanup();
+});
+```
+
+## API reference
+
+### Exports
+
+The default entry (`@rstest/browser-react`) exports:
+
+- `render` - Render a React element into the DOM
+- `renderHook` - Render a custom hook for testing
+- `cleanup` - Unmount all rendered components
+- `act` - Wrap state updates for proper batching
+- `configure` - Configure render behavior (e.g., React Strict Mode)
+
+Type exports:
+
+- `RenderOptions` - Options for `render()`
+- `RenderResult` - Return type of `render()`
+- `RenderHookOptions` - Options for `renderHook()`
+- `RenderHookResult` - Return type of `renderHook()`
+- `RenderConfiguration` - Options for `configure()`
+
+The `/pure` entry exports the same API but does not register automatic cleanup hooks.
+
+### `render(ui, options?)`
+
+Renders a React element into the DOM.
+
+```typescript
+function render(ui: ReactNode, options?: RenderOptions): Promise<RenderResult>;
+
+interface RenderOptions {
+  /** Custom container element to render into */
+  container?: HTMLElement;
+  /** Base element for queries, defaults to document.body */
+  baseElement?: HTMLElement;
+  /** Wrapper component (e.g., for providers/context) */
+  wrapper?: JSXElementConstructor<{ children: ReactNode }>;
+}
+
+interface RenderResult {
+  /** The container element the component is rendered into */
+  container: HTMLElement;
+  /** The base element for queries, defaults to document.body */
+  baseElement: HTMLElement;
+  /** Unmount the rendered component */
+  unmount: () => Promise<void>;
+  /** Re-render the component with new props/element */
+  rerender: (ui: ReactNode) => Promise<void>;
+  /** Returns the rendered UI as a DocumentFragment (useful for snapshots) */
+  asFragment: () => DocumentFragment;
+}
+```
+
+### `renderHook(callback, options?)`
+
+Renders a custom React hook for testing.
+
+```typescript
+function renderHook<Props, Result>(
+  callback: (props?: Props) => Result,
+  options?: RenderHookOptions<Props>,
+): Promise<RenderHookResult<Result, Props>>;
+
+interface RenderHookOptions<Props> extends RenderOptions {
+  /** Initial props passed to the hook */
+  initialProps?: Props;
+}
+
+interface RenderHookResult<Result, Props> {
+  /** Reference to the latest hook return value */
+  result: { current: Result };
+  /** Re-render the hook with new props */
+  rerender: (props?: Props) => Promise<void>;
+  /** Unmount the hook */
+  unmount: () => Promise<void>;
+  /** Access to act for manual state updates */
+  act: (callback: () => unknown) => Promise<void>;
+}
+```
+
+### `act(callback)`
+
+Wraps state updates in React's `act()` for proper batching. Automatically manages the `IS_REACT_ACT_ENVIRONMENT` global.
+
+```typescript
+function act(callback: () => unknown): Promise<void>;
+```
+
+> **Note:** For React 17 (which doesn't export `act`), this function falls back to simple async execution.
+
+### `cleanup()`
+
+Unmounts all rendered components and removes their containers from the DOM.
+
+Called automatically **before** each test when using the default entry. This timing allows you to inspect the DOM after a test failure.
+
+```typescript
+function cleanup(): Promise<void>;
+```
+
+### `configure(options)`
+
+Configure render behavior.
+
+```typescript
+function configure(options: Partial<RenderConfiguration>): void;
+
+interface RenderConfiguration {
+  /** Enable React StrictMode wrapper (default: false) */
+  reactStrictMode: boolean;
+}
+```
+
+## Compatibility
+
+- React 17, 18, and 19
+- Rstest browser mode
+- Node.js >= 18.12.0
+
+## License
+
+MIT

package/dist/879.js

@@ -0,0 +1,111 @@
+import { StrictMode, act, createElement, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+let activeActs = 0;
+function setActEnvironment(value) {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = value;
+}
+function updateActEnvironment() {
+    setActEnvironment(activeActs > 0);
+}
+const _act = act;
+const act_act = 'function' != typeof _act ? async (callback)=>{
+    await callback();
+} : async (callback)=>{
+    activeActs++;
+    updateActEnvironment();
+    try {
+        await _act(callback);
+    } finally{
+        activeActs--;
+        updateActEnvironment();
+    }
+};
+const mountedContainers = new Set();
+const mountedRootEntries = [];
+const config = {
+    reactStrictMode: false
+};
+function pure_createRoot(container) {
+    const root = createRoot(container);
+    return {
+        render: (element)=>root.render(element),
+        unmount: ()=>root.unmount()
+    };
+}
+function strictModeIfNeeded(ui) {
+    return config.reactStrictMode ? /*#__PURE__*/ createElement(StrictMode, null, ui) : ui;
+}
+function wrapUiIfNeeded(ui, wrapper) {
+    return wrapper ? /*#__PURE__*/ createElement(wrapper, null, ui) : ui;
+}
+async function render(ui, options = {}) {
+    const { wrapper } = options;
+    let { container, baseElement } = options;
+    if (!baseElement) baseElement = document.body;
+    if (!container) container = baseElement.appendChild(document.createElement('div'));
+    let root;
+    if (mountedContainers.has(container)) {
+        const entry = mountedRootEntries.find((e)=>e.container === container);
+        if (!entry) throw new Error('Container is tracked but root entry not found');
+        root = entry.root;
+    } else {
+        root = pure_createRoot(container);
+        mountedRootEntries.push({
+            container,
+            root
+        });
+        mountedContainers.add(container);
+    }
+    const wrappedUi = wrapUiIfNeeded(strictModeIfNeeded(ui), wrapper);
+    await act_act(()=>root.render(wrappedUi));
+    return {
+        container,
+        baseElement,
+        unmount: async ()=>{
+            await act_act(()=>root.unmount());
+        },
+        rerender: async (newUi)=>{
+            const wrapped = wrapUiIfNeeded(strictModeIfNeeded(newUi), wrapper);
+            await act_act(()=>root.render(wrapped));
+        },
+        asFragment: ()=>document.createRange().createContextualFragment(container.innerHTML)
+    };
+}
+async function renderHook(renderCallback, options = {}) {
+    const { initialProps, ...renderOptions } = options;
+    const result = {
+        current: void 0
+    };
+    function TestComponent({ hookProps }) {
+        const value = renderCallback(hookProps);
+        useEffect(()=>{
+            result.current = value;
+        });
+        return null;
+    }
+    const { rerender: baseRerender, unmount } = await render(/*#__PURE__*/ createElement(TestComponent, {
+        hookProps: initialProps
+    }), renderOptions);
+    return {
+        result,
+        rerender: async (props)=>{
+            await baseRerender(/*#__PURE__*/ createElement(TestComponent, {
+                hookProps: props
+            }));
+        },
+        unmount,
+        act: act_act
+    };
+}
+async function cleanup() {
+    for (const { root, container } of mountedRootEntries){
+        await act_act(()=>root.unmount());
+        if (container.parentNode === document.body) document.body.removeChild(container);
+    }
+    mountedRootEntries.length = 0;
+    mountedContainers.clear();
+}
+function configure(customConfig) {
+    Object.assign(config, customConfig);
+}
+export { act_act as act, cleanup, configure, render, renderHook };

package/dist/act.d.ts

@@ -0,0 +1,8 @@
+type ActFunction = (callback: () => unknown) => Promise<void>;
+/**
+ * Wraps a callback in React's act() for proper state updates.
+ * Automatically manages IS_REACT_ACT_ENVIRONMENT.
+ */
+export declare const act: ActFunction;
+export {};
+//# sourceMappingURL=act.d.ts.map

package/dist/act.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../src/act.ts"],"names":[],"mappings":"AAiBA,KAAK,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,GAAG,EAAE,WAcX,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { act, cleanup, configure, render, renderHook } from './pure';
+export { render, renderHook, cleanup, act, configure };
+export type { RenderConfiguration, RenderHookOptions, RenderHookResult, RenderOptions, RenderResult, } from './pure';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAQrE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;AACvD,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+import { beforeEach } from "@rstest/core";
+import { cleanup } from "./879.js";
+beforeEach(async ()=>{
+    await cleanup();
+});
+export { act, cleanup, configure, render, renderHook } from "./879.js";

package/dist/pure.d.ts

@@ -0,0 +1,63 @@
+import type { JSXElementConstructor, ReactNode } from 'react';
+import { act } from './act';
+export interface RenderResult {
+    /** The container element the component is rendered into */
+    container: HTMLElement;
+    /** The base element for queries, defaults to document.body */
+    baseElement: HTMLElement;
+    /** Unmount the rendered component */
+    unmount: () => Promise<void>;
+    /** Re-render the component with new props/element */
+    rerender: (ui: ReactNode) => Promise<void>;
+    /** Returns the rendered UI as a DocumentFragment (useful for snapshots) */
+    asFragment: () => DocumentFragment;
+}
+export interface RenderOptions {
+    /** Custom container element to render into */
+    container?: HTMLElement;
+    /** Base element for queries, defaults to document.body */
+    baseElement?: HTMLElement;
+    /** Wrapper component (e.g., for providers/context) */
+    wrapper?: JSXElementConstructor<{
+        children: ReactNode;
+    }>;
+}
+export interface RenderHookOptions<Props> extends RenderOptions {
+    /** Initial props passed to the hook */
+    initialProps?: Props;
+}
+export interface RenderHookResult<Result, Props> {
+    /** Reference to the latest hook return value */
+    result: {
+        current: Result;
+    };
+    /** Re-render the hook with new props */
+    rerender: (props?: Props) => Promise<void>;
+    /** Unmount the hook */
+    unmount: () => Promise<void>;
+    /** Access to act for manual state updates */
+    act: (callback: () => unknown) => Promise<void>;
+}
+export interface RenderConfiguration {
+    /** Enable React StrictMode wrapper */
+    reactStrictMode: boolean;
+}
+/**
+ * Render a React element into the DOM.
+ */
+export declare function render(ui: ReactNode, options?: RenderOptions): Promise<RenderResult>;
+/**
+ * Render a custom React hook for testing.
+ */
+export declare function renderHook<Props, Result>(renderCallback: (props?: Props) => Result, options?: RenderHookOptions<Props>): Promise<RenderHookResult<Result, Props>>;
+/**
+ * Cleanup all mounted components.
+ * Call this in beforeEach or afterEach to prevent test pollution.
+ */
+export declare function cleanup(): Promise<void>;
+/**
+ * Configure render behavior.
+ */
+export declare function configure(customConfig: Partial<RenderConfiguration>): void;
+export { act };
+//# sourceMappingURL=pure.d.ts.map

package/dist/pure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pure.d.ts","sourceRoot":"","sources":["../src/pure.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAG9D,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAI5B,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,SAAS,EAAE,WAAW,CAAC;IACvB,8DAA8D;IAC9D,WAAW,EAAE,WAAW,CAAC;IACzB,qCAAqC;IACrC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,qDAAqD;IACrD,QAAQ,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,2EAA2E;IAC3E,UAAU,EAAE,MAAM,gBAAgB,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,sDAAsD;IACtD,OAAO,CAAC,EAAE,qBAAqB,CAAC;QAAE,QAAQ,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,iBAAiB,CAAC,KAAK,CAAE,SAAQ,aAAa;IAC7D,uCAAuC;IACvC,YAAY,CAAC,EAAE,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB,CAAC,MAAM,EAAE,KAAK;IAC7C,gDAAgD;IAChD,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,wCAAwC;IACxC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,uBAAuB;IACvB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,6CAA6C;IAC7C,GAAG,EAAE,CAAC,QAAQ,EAAE,MAAM,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,eAAe,EAAE,OAAO,CAAC;CAC1B;AA8CD;;GAEG;AACH,wBAAsB,MAAM,CAC1B,EAAE,EAAE,SAAS,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA8CvB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAC5C,cAAc,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,MAAM,EACzC,OAAO,GAAE,iBAAiB,CAAC,KAAK,CAAM,GACrC,OAAO,CAAC,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CA2B1C;AAED;;;GAGG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAS7C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAE1E;AAED,OAAO,EAAE,GAAG,EAAE,CAAC"}

package/dist/pure.js

@@ -0,0 +1 @@
+export { act, cleanup, configure, render, renderHook } from "./879.js";

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@rstest/browser-react",
+  "version": "0.7.9",
+  "type": "module",
+  "description": "React component testing support for Rstest browser mode",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./pure": {
+      "types": "./dist/pure.d.ts",
+      "default": "./dist/pure.js"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rslib build",
+    "dev": "cross-env SOURCEMAP=true rslib build --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "rstest"
+  },
+  "peerDependencies": {
+    "@rstest/core": "workspace:^",
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@rslib/core": "^0.19.0",
+    "@rstest/core": "workspace:*",
+    "@rstest/tsconfig": "workspace:*",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "rstest",
+    "react",
+    "testing",
+    "browser",
+    "component"
+  ],
+  "bugs": {
+    "url": "https://github.com/web-infra-dev/rstest/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/web-infra-dev/rstest",
+    "directory": "packages/browser-react"
+  },
+  "engines": {
+    "node": ">=18.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}