Package Exports
- @solidjs/testing-library
Readme
Simple and complete Solid DOM testing utilities that encourage good testing practices.
Inspired completely by preact-testing-library
Table of Contents
The Problem
You want to write tests for your Solid components so that they avoid including implementation details, and are maintainable in the long run.
The Solution
The Solid Testing Library is a very lightweight solution for testing Solid components. Its primary guiding principle is:
The more your tests resemble the way your software is used, the more confidence they can give you.
Installation
This module is distributed via npm which is bundled with node and should be installed
as one of your project's devDependencies
:
npm install --save-dev @solidjs/testing-library
If you using Jest we recommend using solid-jest to properly resolve the browser version of Solid as Jest will default to the server version when run in Node.
💡 If you are using Jest or vitest, you may also be interested in installing @testing-library/jest-dom
so you can use
the custom jest matchers.
Integration with Vite
A working Vite template setup with solid-testing-library
and TypeScript support can be found here.
Docs
See the docs over at the Testing Library website.
There are several key differences, though:
⚠️ The render
function takes in a function that returns a Solid Component, rather than simply the component itself.
// With @testing-library/preact
const results = render(<YourComponent />, options);
// With solid-testing-library
const results = render(() => <YourComponent />, options);
⚠️ Solid.js does not rerender, it merely executes side effects triggered by reactive state that change the DOM, therefore there is no rerender method. You can use global signals to manipulate your test component in a way that causes it to update.
Solid.js' reactive changes are pretty instantaneous, so there is rarely need to use waitFor(…)
or await findByRole(…)
- with the exception of transitions and Suspense.
⚠️ Solid.js external reactive state does not require any DOM elements to run in, so our renderHook
call has no container
, baseElement
or queries in its options or return value. Instead, it has an owner
to be used with runWithOwner
if required. It also exposes a cleanup
function, though this is already automatically called after the test is finished.
function renderHook<Args extends any[], Result>(
hook: (...args: Args) => Result,
options: {
initialProps?: Args,
wrapper?: Component<{ children: JSX.Element }>
}
) => {
result: Result;
owner: Owner | null;
cleanup: () => void;
}
This can be used to easily test a hook / primitive:
const { result } = renderHook(createResult);
expect(result).toBe(true);
If you are using a wrapper
with renderHook
, make sure it will always return props.children
- especially if you are using a context with asynchronous code together with <Show>
, because this is required to get the value from the hook and it is only obtained synchronously once and you will otherwise only get undefined
and wonder why this is the case.
⚠️ Solid.js supports custom directives, which is a convenient pattern to tie custom behavior to elements, so we also have a renderDirective
call, which augments renderHook
to take a directive as first argument, accept an initialValue
for the argument and a targetElement
(string, HTMLElement or function returning a HTMLElement) in the options
and also returns arg
and setArg
to read and manipulate the argument of the directive.
function renderDirective<
Arg extends any,
Elem extends HTMLElement
>(
directive: (ref: Elem, arg: Accessor<Arg>) => void,
options?: {
...renderOptions,
initialValue: Arg,
targetElement:
| Lowercase<Elem['nodeName']>
| Elem
| (() => Elem)
}
): Result & { arg: Accessor<Arg>, setArg: Setter<Arg> };
This allows for very effective and concise testing of directives:
const { asFragment, setArg } = renderDirective(myDirective);
expect(asFragment()).toBe(
'<div data-directive="works"></div>'
);
setArg("perfect");
expect(asFragment()).toBe(
'<div data-directive="perfect"></div>'
);
⚠️ Solid.js manages side effects with different variants of createEffect
. While you can use waitFor
to test asynchronous effects, it uses polling instead of allowing Solid's reactivity to trigger the next step. In order to simplify testing those asynchronous effects, we have a testEffect
helper that complements the hooks for directives and hooks:
testEffect(fn: (done: (result: T) => void) => void, owner?: Owner): Promise<T>
// use it like this:
test("testEffect allows testing an effect asynchronously", () => {
const [value, setValue] = createSignal(0);
return testEffect(done => createEffect((run: number = 0) => {
if (run === 0) {
expect(value()).toBe(0);
setValue(1);
} else if (run === 1) {
expect(value()).toBe(1);
done();
}
return run + 1;
}));
});
It allows running the effect inside a defined owner that is received as an optional second argument. This can be useful in combination with renderHook
, which gives you an owner field in its result. The return value is a Promise with the value given to the done()
callback. You can either await the result for further assertions or return it to your test runner.
Issues
If you find any issues, please check on the issues page if they are already known. If not, opening an issue will be much appreciated, even more so if it contains a
- short description
- minimal reproduction code
- list of possible workarounds, if there are any
If you think you can fix an issue yourself, feel free to open a pull-request. If functionality changes, please don't forget to add or adapt tests.
Acknowledgment
Thanks goes to Kent C. Dodds and his colleagues for creating testing-library and to the creators of preact-testing-library.
This library has been created by Ryan Carniato and is currently maintained by Alex Lohr.