Skip to main content

API

Due to being inspired by the preact-testing-library you can check its page for more information.

There are several key differences, to be aware of.

render​

The render function takes in a function that returns a Solid Component, rather than simply the component itself.

const results = render(() => <YourComponent />, options)

Solid.js does not re-render, 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.

In addition to the original API, the render function of this testing library supports a convenient location option that will set up an in-memory router pointing at the specified location. Since this setup is not synchronous, you need to first use asynchronous queries (findBy) after employing it:

it('uses params', async () => {
  const App = () => (
    <>
      <Route path="/ids/:id" component={() => <p>Id: {useParams()?.id}</p>} />
      <Route path="/" component={() => <p>Start</p>} />
    </>
  )
  const {findByText} = render(() => <App />, {location: 'ids/1234'})
  expect(await findByText('Id: 1234')).not.toBeFalsy()
})

It uses @solidjs/router, so if you want to use a different router, you should consider the wrapper option instead. If you attempt to use this without having the package installed, you will receive an error message.

renderHook​

Solid.js external reactive state does not require any DOM elements to run in, so our renderHook call to test hooks in the context of a component (if your hook does not require the context of a component, createRoot should suffice to test the reactive behavior; for convenience, we also have createEffect, which is described in the Async methods section) 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.

renderDirective​

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 an 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>')

Async methods​

Solid.js reactive changes are pretty instantaneous, so there is rarely need to use waitFor(…), await findByRole(…) and other asynchronous queries to test the rendered result, except for transitions, suspense, resources and router navigation.

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.

Known issues​

If you are using vitest, then tests might fail, because the packages solid-js, and @solidjs/router (if used) need to be loaded only once, and they could be loaded both through the internal vite server and through node. Typical bugs that happen because of this is that dispose is supposedly undefined, or the router could not be loaded.

Since version 2.8.2, our vite plugin has gained the capability to configure everything for testing, so you should only need extra configuration for globals, coverage, etc.