Svelte-component-double NPM

svelte-component-double

An test double for Svelte components. It works with Vitest, Jest and Jasmine.

Installation

First install the package:

npm install --save-dev svelte-component-double

Vitest setup & usage

Create a file in your Vite project, named test/registerSvelteComponentDouble.js, with the followig content:

import { expect } from 'vitest';
import * as matchers from 'svelte-component-double/vitest';

expect.extend(matchers);

import { componentDouble } from 'svelte-component-double';

globalThis.componentDouble = componentDouble;

Then update your vi.config.js file to include this as a setup file for Vitest:

const config = {
  ...,
  test: {
    ...,
    setupFiles: [
      ...,
      './test/registerSvelteComponentDouble.js'
    ]
  }
}

Then you can begin to write mocked tests like this:

import {
	describe,
	it,
	expect,
	beforeEach,
	vi
} from 'vitest';
import {
	render,
	screen
} from '@testing-library/svelte';
import Child from './Child.svelte';
import Parent from './Parent.svelte';

vi.mock('./Child.svelte', async () => ({
	default: componentDouble('Child')
}));

describe('Parent component', () => {
	beforeEach(Child.reset);

  it('renders a Child with the right props', () => {
		render(Parent);

    expect(Child).toBeRenderedWithProps({
      foo: "bar"
    });
  });
});

Since mocks are active for the entire module, you may wish to place mocked tests in a separate test file e.g. parent.mocks.test.js, keeping parent.test.js free for non-mocked tests.

Jasmine setup & usage

Add the following helper in spec/support/jasmine.json.

"helpers": [
  "../node_modules/svelte-component-double/lib/matchers/jasmine.js"
]

You'll need to use a mocking tool like babel-plugin-rewire-exports.

In the example below, Parent is the component under test, and Child is being spied on.

import Child, { rewire as rewire$Child, restore } from '../src/Child.svelte';
import Parent from '../src/Parent.svelte';

import { componentDouble } from 'svelte-component-double';

describe('Parent component', () => {
  it('renders a Child', () => {
    // ensure JSDOM is set up and ready to go

    rewire$Child(componentDouble(Child));

    const el = document.createElement('div');
    new Parent({ target: el });

    expect(Child).toHaveBeenCalled();
    expect(el.querySelector(spySelector(Child))).not.toBeNull();
  });
});

Matchers

The expect(component) function has the following matchers available.

Matcher	Description
`toBeRendered()`	Passes if there was at least one instance of the component instantiated in the current document.
`toBeRenderedIn(container)`	Same but with a specific DOM container instead of	`document.body`.
`toBeRenderedWithProps(props)`	Passes if there was at least one instance of the component instantiated with these exact props.
`toBeRenderedWithPropsIn(props, container)`	Same as above but with a specic DOM container instead of `document.body`.

Identifying stubbed DOM elements

A spied/stubbed component will be rendered into the DOM like this:

<div class="spy-ComponentName" id="spy-ComponentName-instanceNumber" />

You can use the selector function to return a selector that will match all instances of a rendered double. So for the example above, calling spySelector(Child) will return "div[class=spy-Child]".

You can use the instanceSelector(n) to return a selector that matches a specific instance of the component.

Triggering two-way bindings

If your stubbed component uses a two-way binding you can trigger that binding to update using the updateBoundValue function.

For example, say you have the component TagList which can be used like this:

<TagList bind:tags={tags} />

Then you can test how your component responds to updates to tags like this:

rewire$TagList(componentDouble(TagList));
mount(<your component that uses TagList>);

TagList.firstInstance().updateBoundValue(
  component, "tags", ["a", "b", "c"]);

Warning: updateBoundValue has been tested with Svelte version 3.16. It is incompatible with 3.15 and below.

Component property reference

All of these functions are available on your component double type.

Property/function	Type	Description
`instances`	Array of instances	Each instance of the component that has been rendered.
`reset()`	Function	Resets a mocked component between tests. Call this in your `beforeEach` block.
`selector()`	Function	Selector for all instances of this double.
`instanceSelector(n)`	Function	Selector for a single instances of this double.
`findMatching(matchFn)`	Function	Find the call whose props match the `matchFn` predicate
`firstInstance()`	Function	Returns the first instance of a component, which you an then manipulate using functions such as `updateBoundValue` (see note above).
`lastInstance()`	Function	Returns the last instance of a component.
`getInstanceFromElement(domElement)`	Function	Returns the component instance that rendered the given DOM element.
`mountedInstances()`	Function	Returns only the instances that are currently rendered in the DOM.
`propsOfAllInstances()`	Function	Returns an array for props for each of the rendered instance of this component.
`dispatch(event)`	Function	Dispatches an event to the last rendered component. You can also call `dispatch` on individual instances.