align functionality with original:

- add wrapper support
- add asFragment method
- add renderHook function

improve documentation + tests

Author: Alex Lohr

.babelrc

@@ -1,6 +1,7 @@
+<h1>
+  <img width="100%" src="https://assets.solidjs.com/banner?type=core&project=solid-testing-library" alt="Solid Testing Library">
+</h1>
 <div align="center">
-<h1>Solid Testing Library</h1>
-
 <p>Simple and complete Solid DOM testing utilities that encourage good testing
 practices.</p>
 
@@ -13,14 +14,18 @@ practices.</p>
 
 </div>
 
-<hr />
+---
 
 ## Table of Contents
 
 - [The Problem](#the-problem)
 - [The Solution](#the-solution)
 - [Installation](#installation)
 - [Docs](#docs)
+- [Issues](#issues)
+- [Acknowledgement](#acknowledgment)
+
+---
 
 ## The Problem
 
@@ -38,16 +43,39 @@ The Solid Testing Library is a very lightweight solution for testing Solid compo
 This module is distributed via npm which is bundled with node and should be installed
 as one of your project's `devDependencies`:
 
-```
+```sh
 npm install --save-dev solid-testing-library
 ```
+
 If you using Jest we recommend using [solid-jest](https://github.com/solidjs/solid-jest) to properly resolve the browser version of Solid as Jest will default to the server version when run in Node.
 
-💡 You may also be interested in installing `@testing-library/jest-dom` so you can use
+💡 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](https://github.com/testing-library/jest-dom).
 
 ## Docs
 
-TODO
-<!-- See the [docs](https://testing-library.com/docs/preact-testing-library/intro) over at the Testing
-Library website. -->
+See the [docs](https://testing-library.com/docs/preact-testing-library/intro) over at the Testing Library website.
+
+There are two key difference, though:
+
+⚠️ 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`](https://www.solidjs.com/docs/latest/api#runwithowner) if required. It also exposes a `cleanup` function, though this is already automatically called after the test is finished.
+
+## Issues
+
+If you find any issues, please [check on the issues page](https://github.com/solidjs/solid-testing-library/issues) 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](https://github.com/solidjs/solid-testing-library/pulls). If functionality changes, please don't forget to add or adapt tests.
+
+## Acknowledgment
+
+Thanks goes to [Kent C. Dodds](https://kentcdodds.com/) and his colleagues for creating testing-library and to the creators of [preact-testing-library](https://github.com/testing-library/preact-testing-library).
+
+This library has been created by Ryan Carniato and is currently maintained by Alex Lohr.

README.md

@@ -1,6 +1,6 @@
 {
   "name": "solid-testing-library",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Simple and complete Solid testing utilities that encourage good testing practices.",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,9 @@
   },
   "license": "MIT",
   "author": "Ryan Carniato",
-  "maintainers": ["Alex Lohr"],
+  "maintainers": [
+    "Alex Lohr"
+  ],
   "homepage": "https://github.com/solidjs/solid-testing-library#readme",
   "repository": {
     "type": "git",
@@ -49,6 +51,7 @@
     "test:watch": "npm test --watch",
     "test:coverage": "npm test -- --coverage",
     "setup": "npm install && npm run validate",
+    "prettier": "prettier -w src/**/* ./*.json ./vitest.config.js",
     "validate": "npm run typecheck && npm run test:coverage && npm run build",
     "report:coverage": "cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage"
   },

package.json

@@ -1,6 +1,6 @@
 import "@testing-library/jest-dom/extend-expect";
 import { createSignal, createEffect } from "solid-js";
-import { render, screen } from "..";
+import { render, renderHook, screen } from "..";
 import userEvent from "@testing-library/user-event";
 
 declare global {
@@ -71,3 +71,22 @@ test("queries should not return elements outside of the container", () => {
   container.parentNode!.insertBefore(falseContainer, getAllByText("Some text...")[0].parentNode);
   expect(getAllByText("Some text...")[0] === container.childNodes[0]).toBe(true);
 });
+
+test("wrapper option works correctly", () => {
+  const { asFragment } = render(() => <div>Component</div>, {
+    wrapper: props => <div>Wrapper {props.children}</div>
+  });
+  expect(asFragment()).toBe("<div>Wrapper <div>Component</div></div>");
+});
+
+test("renderHook works correctly", () => {
+  const createDate = () => {
+    const [date, setDate] = createSignal(new Date());    
+    return [date, (d: Date) => d ? setDate(d) : setDate(new Date())] as const;
+  }
+  const { result: [ date, setDate ] } = renderHook(createDate);
+  expect(date()).toBeInstanceOf(Date);
+  const newDate = new Date();
+  setDate(newDate);
+  expect(date()).toBe(newDate);
+});

src/__tests__/basic.tsx

@@ -29,9 +29,9 @@ test("debug pretty prints multiple containers", () => {
     </>
   );
 
-  render(() => <HelloWorld />);
-  const multipleElements = screen.getAllByTestId("testId");
-  screen.debug(multipleElements);
+  const { debug, getAllByTestId } = render(() => <HelloWorld />);
+  const multipleElements = getAllByTestId("testId");
+  debug(multipleElements);
   expect(console.log).toHaveBeenCalledTimes(2);
   expect(console.log).toHaveBeenCalledWith(expect.stringContaining("Hello World"));
 });

src/__tests__/debug.tsx

@@ -4,4 +4,4 @@
     "types": ["vitest/globals", "@testing-library/jest-dom"]
   },
   "include": ["./*.tsx"]
-}
+}

src/__tests__/tsconfig.json

@@ -1,30 +1,22 @@
 import { getQueriesForElement, prettyDOM } from "@testing-library/dom";
+import { createRoot, getOwner } from "solid-js";
 import { hydrate as solidHydrate, render as solidRender } from "solid-js/web";
 
-import type { Ui, Result, Options, Ref } from "./types";
-
-/**
- * Shim for the teardown function
- */
-declare var teardown: Function | undefined;
+import type { Ui, Result, Options, Ref, RenderHookResult, RenderHookOptions } from "./types";
 
 /* istanbul ignore next */
 if (!process.env.STL_SKIP_AUTO_CLEANUP) {
   if (typeof afterEach === "function") {
     afterEach(async () => {
       await cleanup();
     });
-  } else if (typeof teardown === "function") {
-    teardown(async () => {
-      await cleanup();
-    });
   }
 }
 
 const mountedContainers = new Set<Ref>();
 
 function render(ui: Ui, options: Options = {}): Result {
-  let { container, baseElement = container, queries, hydrate = false } = options;
+  let { container, baseElement = container, queries, hydrate = false, wrapper } = options;
 
   if (!baseElement) {
     // Default to document.body instead of documentElement to avoid output of potentially-large
@@ -36,9 +28,13 @@ function render(ui: Ui, options: Options = {}): Result {
     container = baseElement.appendChild(document.createElement("div"));
   }
 
+  const wrappedUi: Ui = typeof wrapper === 'function'
+    ? () => wrapper!({ children: ui() })
+    : ui;
+
   const dispose = hydrate
-    ? ((solidHydrate(ui, container) as unknown) as () => void)
-    : solidRender(ui, container);
+    ? ((solidHydrate(wrappedUi, container) as unknown) as () => void)
+    : solidRender(wrappedUi, container);
 
   // We'll add it to the mounted containers regardless of whether it's actually
   // added to document.body so the cleanup method works regardless of whether
@@ -48,6 +44,7 @@ function render(ui: Ui, options: Options = {}): Result {
   const queryHelpers = getQueriesForElement(container, queries)
 
   return {
+    asFragment: () => container?.innerHTML as string,
     container,
     baseElement,
     debug: (el = baseElement, maxLength, options) =>
@@ -59,11 +56,20 @@ function render(ui: Ui, options: Options = {}): Result {
   } as Result;
 }
 
+export function renderHook<A extends any[], R>(hook: (...args: A) => R, options?: RenderHookOptions<A>): RenderHookResult<R> {
+  const initialProps: A | [] = Array.isArray(options) ? options : options?.initialProps || [];
+  const [dispose, owner, result] = createRoot((dispose) => [dispose, getOwner(), hook(...initialProps as A)]);
+
+  mountedContainers.add({ dispose });
+
+  return { result, cleanup: dispose, owner };
+}
+
 function cleanupAtContainer(ref: Ref) {
   const { container, dispose } = ref;
   dispose();
 
-  if (container.parentNode === document.body) {
+  if (container?.parentNode === document.body) {
     document.body.removeChild(container);
   }
 

src/index.ts

@@ -1,9 +1,9 @@
-import type { JSX } from "solid-js";
+import type { Component, JSX, Owner } from "solid-js";
 import { queries } from "@testing-library/dom";
 import type { Queries, BoundFunctions, prettyFormat } from "@testing-library/dom";
 
 export interface Ref {
-  container: HTMLElement;
+  container?: HTMLElement;
   dispose: () => void;
 }
 
@@ -14,6 +14,7 @@ export interface Options {
   baseElement?: HTMLElement;
   queries?: Queries & typeof queries;
   hydrate?: boolean;
+  wrapper?: Component<{ children: JSX.Element }>;
 }
 
 export type DebugFn = (
@@ -23,8 +24,19 @@ export type DebugFn = (
 ) => void;
 
 export type Result = BoundFunctions<typeof queries> & {
+  asFragment: () => string;
   container: HTMLElement;
   baseElement: HTMLElement;
   debug: DebugFn;
   unmount: () => void;
-} ;
+};
+
+export type RenderHookOptions<A extends any[]> = {
+  initialProps?: A
+} | A;
+
+export type RenderHookResult<R> = {
+  result: R;
+  owner: Owner | null;
+  cleanup: () => void;
+};

src/types.ts

@@ -13,5 +13,5 @@
     "outDir": "./dist",
     "module": "commonjs"
   },
-  "include": ["src/index.ts", "src/types.ts"],
+  "include": ["src/index.ts", "src/types.ts"]
 }

tsconfig.json

@@ -14,7 +14,7 @@ export default defineConfig({
     transformMode: {
       web: [/\.[jt]sx?$/]
     },
-    include: 'src/__tests__/*.tsx'
+    include: "src/__tests__/*.tsx"
   },
   resolve: {
     conditions: ["browser", "development"]