{"id":21954364,"url":"https://github.com/delph123/supplejs-testing-library","last_synced_at":"2026-01-03T21:43:22.385Z","repository":{"id":246904003,"uuid":"824714116","full_name":"delph123/supplejs-testing-library","owner":"delph123","description":"Simple and complete SuppleJS testing utilities that encourage good testing practices.","archived":false,"fork":false,"pushed_at":"2024-07-19T22:47:45.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-06T03:38:54.543Z","etag":null,"topics":["supplejs","testing-framework","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/delph123.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-05T18:58:48.000Z","updated_at":"2024-07-19T22:47:48.000Z","dependencies_parsed_at":"2024-07-05T20:46:49.134Z","dependency_job_id":"ab6f5128-b0c6-4478-a5a4-4727875630e1","html_url":"https://github.com/delph123/supplejs-testing-library","commit_stats":null,"previous_names":["delph123/supplejs-testing-library"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/delph123%2Fsupplejs-testing-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/delph123%2Fsupplejs-testing-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/delph123%2Fsupplejs-testing-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/delph123%2Fsupplejs-testing-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/delph123","download_url":"https://codeload.github.com/delph123/supplejs-testing-library/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244020792,"owners_count":20385012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["supplejs","testing-framework","unit-testing"],"created_at":"2024-11-29T07:18:01.570Z","updated_at":"2026-01-03T21:43:22.329Z","avatar_url":"https://github.com/delph123.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003ch1\u003eSuppleJS Testing Library\u003c/h1\u003e\n\u003cp\u003eSimple and complete Solid DOM testing utilities that encourage good testing practices.\u003c/p\u003e\n\n\u003e Inspired completely by [solid-testing-library](https://github.com/solidjs/solid-testing-library) and [preact-testing-library](https://github.com/testing-library/preact-testing-library)\n\n[![NPM Version](https://img.shields.io/npm/v/supplejs-testing-library.svg)](https://www.npmjs.com/package/supplejs-testing-library)\n[![GitHub License](https://img.shields.io/github/license/delph123/supplejs-testing-library)](https://github.com/delph123/supplejs-testing-library/blob/main/LICENSE)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/delph123/supplejs-testing-library/validate.yml?branch=main\u0026logo=github)](https://github.com/delph123/supplejs-testing-library/actions/workflows/validate.yml)\n[![codecov](https://codecov.io/gh/delph123/supplejs-testing-library/graph/badge.svg?token=AJNU0N5YI7)](https://codecov.io/gh/delph123/supplejs-testing-library)\n\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n-   [The Problem](#the-problem)\n-   [The Solution](#the-solution)\n-   [Installation](#installation)\n-   [Docs](#docs)\n-   [Issues](#issues)\n-   [Acknowledgement](#acknowledgment)\n\n---\n\n## The Problem\n\nYou want to write tests for your Solid components so that they avoid including implementation details, and are maintainable in the long run.\n\n## The Solution\n\nThe Solid Testing Library is a very lightweight solution for testing Solid components. Its primary guiding principle is:\n\n\u003e [The more your tests resemble the way your software is used, the more confidence they can give you.](https://twitter.com/kentcdodds/status/977018512689455106)\n\n## Installation\n\nThis module is distributed via npm which is bundled with node and should be installed as one of your project's `devDependencies`:\n\n```sh\nnpm install --save-dev supplejs-testing-library\n```\n\n💡 If you are using Jest or vitest, you may also be interested in installing `@testing-library/jest-dom` so you can use\n[the custom jest matchers](https://github.com/testing-library/jest-dom).\n\n## Integration with Vite\n\nA working Vite template setup with `supplejs-testing-library` and TypeScript support can be found [here](https://github.com/delph123/supplejs-templates/tree/main/ts-vitest).\n\n## Docs\n\nSee the [docs for `preact-testing-library`](https://testing-library.com/docs/preact-testing-library/intro) over at the Testing Library website. `supplejs-testing-library` is pretty similar.\n\nThere are several key differences, though:\n\n#### `render`\n\n⚠️ The `render` function takes in a function that returns a SuppleJS Component, rather than simply the component itself.\n\n```tsx\n// With @testing-library/preact\nconst results = render(\u003cYourComponent /\u003e, options);\n```\n\n```tsx\n// With supplejs-testing-library\nconst results = render(() =\u003e \u003cYourComponent /\u003e, options);\n```\n\n⚠️ SuppleJS does _not_ re-render, it merely executes side effects triggered by reactive states 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.\n\nSuppleJS 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 suspense, resources, lazy loaded components, some effects (createEffect, createDeferred, onMount) and error boundaries.\n\n#### `renderHook`\n\n⚠️ SuppleJS 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 `testEffect`, which is described later) 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.\n\n```ts\nfunction renderHook\u003cArgs extends any[], Result\u003e(\n  hook: (...args: Args) =\u003e Result,\n  options: {\n    initialProps?: Args,\n    wrapper?: Component\u003c{ children: JSX.Element }\u003e\n  }\n) =\u003e {\n  result: Result;\n  owner: Owner | null;\n  cleanup: () =\u003e void;\n}\n```\n\nThis can be used to easily test a hook / primitive:\n\n```ts\nconst { result } = renderHook(createResult);\nexpect(result).toBe(true);\n```\n\nIf 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 `\u003cShow\u003e`, 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.\n\n#### `testEffect`\n\nSuppleJS 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:\n\n```ts\ntestEffect(fn: (done: (result: T) =\u003e void) =\u003e void, owner?: Owner): Promise\u003cT\u003e\n\n// use it like this:\ntest(\"testEffect allows testing an effect asynchronously\", () =\u003e {\n  const [v, setValue] = createSignal(0);\n  const value = createDeferred(v);\n  return testEffect((done) =\u003e\n    createEffect((run: number = 0) =\u003e {\n      if (run === 0) {\n        expect(value()).toBe(0);\n        setValue(1);\n      } else if (run === 1) {\n        expect(value()).toBe(1);\n        done();\n      }\n      return run + 1;\n    })\n  );\n});\n```\n\nIt 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.\n\n#### `cleanup`\n\nThe `cleanup` function cleans-up any rendered context. It is installed automatically when afterEach is globally available (as is the case when using option `globals: true` in vitest config).\n\nIf you don't want to set `globals: true`, it is possible to manually install the cleanup function in a setup file.\n\n```ts\n// vitest-setup.ts\nimport { afterEach } from \"vitest\";\nimport { cleanup } from \"supplejs-testing-library\";\n\nafterEach(() =\u003e cleanup());\n\n// vite.config.ts\nexport default defineConfig({\n    test: {\n        setupFiles: [\"vitest-setup.ts\"],\n    },\n});\n```\n\n## Acknowledgement\n\nThanks goes to [Kent C. Dodds](https://kentcdodds.com/) and his colleagues for creating testing-library and to the creators of [solid-testing-library](https://github.com/solidjs/solid-testing-library).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdelph123%2Fsupplejs-testing-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdelph123%2Fsupplejs-testing-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdelph123%2Fsupplejs-testing-library/lists"}