add renderDirective method

improve documentation

Author: Alex Lohr

README.md

@@ -80,6 +80,59 @@ Solid.js' reactive changes are pretty instantaneous, so there is rarely need to
 
 ⚠️ 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.
 
+```ts
+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:
+
+```ts
+const { result } = renderHook(createResult);
+expect(result).toBe(true);
+```
+
+⚠️ Solid.js supports [custom directives](https://www.solidjs.com/docs/latest/api#use___), 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.
+
+```ts
+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:
+
+```ts
+const { asFragment, setArg } = renderDirective(myDirective);
+expect(asFragment()).toBe(
+  '<div data-directive="works"></div>'
+);
+setArg("perfect");
+expect(asFragment()).toBe(
+  '<div data-directive="perfect"></div>'
+);
+```
+
 ## 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

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidjs/testing-library",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Simple and complete Solid testing utilities that encourage good testing practices.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -64,7 +64,7 @@
     "@testing-library/user-event": "^14.4.3",
     "coveralls": "^3.1.1",
     "jsdom": "^21.0.0",
-    "prettier": "^2.8.2",
+    "prettier": "^2.8.3",
     "pretty-format": "^29.3.1",
     "solid-js": "^1.6.9",
     "tsup": "6.5.0",

package.json

@@ -1,8 +1,15 @@
 import "@testing-library/jest-dom/extend-expect";
-import { createSignal, createEffect, createContext, useContext, ParentComponent } from "solid-js";
-import { render, renderHook, screen } from "..";
+import {
+  createSignal,
+  createEffect,
+  createContext,
+  useContext,
+  ParentComponent,
+  Accessor
+} from "solid-js";
+import type { JSX } from "solid-js";
+import { render, renderDirective, renderHook, screen } from "..";
 import userEvent from "@testing-library/user-event";
-import { m } from "vitest/dist/index-2f5b6168";
 
 declare global {
   var _$HY: Record<string, any>;
@@ -122,3 +129,37 @@ test("wrapper context is available in renderHook", () => {
   const { result } = renderHook(testHook, { wrapper: Wrapper });
   expect(result).toBe("context value");
 });
+
+declare module "solid-js" {
+  namespace JSX {
+    interface Directives {
+      noArgDirective: boolean;
+      argDirective: string;
+    }
+  }
+}
+
+type NoArgDirectiveArg = Accessor<JSX.Directives["noArgDirective"]>;
+
+test("renderDirective works for directives without an argument", () => {
+  const noArgDirective: (ref: HTMLElement, arg: NoArgDirectiveArg) => void = (ref: HTMLElement) => {
+    ref.dataset.directive = "works";
+  };
+  const { asFragment } = renderDirective(noArgDirective);
+  expect(asFragment()).toBe('<div data-directive="works"></div>');
+});
+
+test("renderDirective works for directives with argument", () => {
+  const argDirective = (ref: HTMLSpanElement, arg: Accessor<string>) => {
+    createEffect(() => {
+      ref.dataset.directive = arg();
+    });
+  };
+  const { asFragment, setArg } = renderDirective(argDirective, {
+    initialValue: "initial value",
+    targetElement: "span"
+  });
+  expect(asFragment()).toBe('<span data-directive="initial value"></span>');
+  setArg("updated value");
+  expect(asFragment()).toBe('<span data-directive="updated value"></span>');
+});

src/__tests__/basic.tsx

@@ -1,8 +1,8 @@
 import { getQueriesForElement, prettyDOM } from "@testing-library/dom";
-import { ComponentProps, createComponent, createRoot, getOwner, JSX } from "solid-js";
+import { Accessor, ComponentProps, createComponent, createRoot, createSignal, getOwner, JSX, onMount, Setter } from "solid-js";
 import { hydrate as solidHydrate, render as solidRender } from "solid-js/web";
 
-import type { Ui, Result, Options, Ref, RenderHookResult, RenderHookOptions } from "./types";
+import type { Ui, Result, Options, Ref, RenderHookResult, RenderHookOptions, RenderDirectiveOptions, RenderDirectiveResult } from "./types";
 
 /* istanbul ignore next */
 if (!process.env.STL_SKIP_AUTO_CLEANUP) {
@@ -80,6 +80,26 @@ export function renderHook<A extends any[], R>(
   return { result, cleanup: dispose, owner };
 }
 
+export function renderDirective<A extends any, U extends A, E extends HTMLElement>(
+  directive: (ref: E, arg: Accessor<U>) => void,
+  options?: RenderDirectiveOptions<U, E>
+): RenderDirectiveResult<U> {
+  const [arg, setArg] = createSignal(options?.initialValue as U);
+  return Object.assign(render(() => {
+    const targetElement = options?.targetElement &&
+      (options.targetElement instanceof HTMLElement
+        ? options.targetElement
+        : typeof options.targetElement === 'string'
+        ? document.createElement(options.targetElement)
+        : typeof options.targetElement === 'function'
+        ? options.targetElement()
+        : undefined) ||
+      document.createElement('div');
+    onMount(() => directive(targetElement as E, arg as Accessor<U>));
+    return targetElement;
+  }, options), { arg, setArg });
+}
+
 function cleanupAtContainer(ref: Ref) {
   const { container, dispose } = ref;
   dispose();

src/index.ts

@@ -1,4 +1,4 @@
-import type { Component, JSX, Owner } from "solid-js";
+import type { Accessor, Component, JSX, Owner, Setter } from "solid-js";
 import { queries } from "@testing-library/dom";
 import type { Queries, BoundFunctions, prettyFormat } from "@testing-library/dom";
 
@@ -41,3 +41,13 @@ export type RenderHookResult<R> = {
   owner: Owner | null;
   cleanup: () => void;
 };
+
+export type RenderDirectiveOptions<A extends any, E extends HTMLElement = HTMLDivElement> = Options & {
+  initialValue?: A;
+  targetElement?: Lowercase<E['nodeName']> | E | (() => E);
+};
+
+export type RenderDirectiveResult<A extends any> = Result & {
+  arg: Accessor<A>,
+  setArg: Setter<A>
+};