API

configure()

configure(options: GlobalOptions): void

Define global options that will be used across all tests.

import { configure } from 'rut-dom';
configure({
strict: true,
});

Options

debugger

DebugOptions

Debug options that will be applied to every debug() call. Can override these options on a per-call basis.

configure({
debugger: {
reactElements: false,
},
});

mockRef()

(element: React.ReactElement) => unknown

Mock a ref found within the current render tree. This mock function is passed the React element being referenced, for use in determining and providing a custom mock. For example:

import { render } from 'rut-dom';
const spy = jest.fn();
const { root } = render<LoginFormProps>(<LoginForm />, {
mockRef(element) {
if (element.type === 'input' && element.props.type === 'password') {
return { onChange: spy };
}
},
});
root.findOne('input').dispatch('onChange');
expect(spy).toHaveBeenCalled();

strict

boolean

Wraps the root element in React.StrictMode, logging all deprecations within the current tree. Can be used in unison with the wrapper option below.

render<ButtonProps>(<Button>Save</Button>, {
strict: true,
});

wrapper

React.ReactElement

Wraps the root element in the provided React element. Useful for wrapping shared functionality across multiple test suites, like contexts. Can be used in unison with the strict option above.

function Wrapper({ children }: { children?: React.ReactNode }) {
return (
<ThemeContext.Provider value="dark">
<DirectionContext.Provider value="ltr">{children}</DirectionContext.Provider>
</ThemeContext.Provider>
);
}
render<ButtonProps>(<Button>Save</Button>, {
wrapper: <Wrapper />,
});

The wrapping component must render children.

render()

render\(element: React.ReactElement, options?: RendererOptions): Result\

Accepts a React element and an optional options object, and returns a rendered result. This function is merely a wrapper around react-test-renderer, providing additional functionality, and an improved API.

import { render } from 'rut-dom';
test('renders a button', () => {
const result = render<ButtonProps>(<Button>Save</Button>);
});

If using TypeScript, it's highly encouraged to pass the props interface as a generic to render, so that props, children, and other features can be typed correctly. This information is currently not inferrable as JSX.Element does not persist types.

Furthermore, if the root is a host component (DOM element), you can apply props using the InferComponentProps utility type. This isn't always necessary, only when prop information is required.

import { render, InferComponentProps } from 'rut-dom';
test('renders a native button', () => {
const result = render<InferComponentProps<'button'>>(<button type="submit">Save</button>);
});

renderAndWait()

async renderAndWait\(element: React.ReactElement, options?: RendererOptions): Result\

Works in a similar fashion to render() but also waits for async calls within the mounting phase to complete before returning the rendered result. Because of this, the function must be awaited.

import { renderAndWait } from 'rut-dom';
test('renders a user profile', async () => {
const result = await renderAndWait<UserProfileProps>(<UserProfile id={1} />);
});