Merge pull request #1 from phryneas/pr/api-bikeshedding

Author: phryneas

package.json

@@ -49,6 +49,7 @@
   ],
   "dependencies": {
     "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.0.1",
     "jsdom": "^25.0.1",
     "rehackt": "^0.1.0"
   },

src/assertable.ts

@@ -0,0 +1,26 @@
+import { RenderStream } from "./profile/profile.js";
+
+export const assertableSymbol = Symbol.for(
+  "@testing-library/react-render-stream:assertable"
+);
+
+/**
+ * A function or object that can be used in assertions, like e.g.
+ ```ts
+ expect(assertable).toRerender()
+ expect(assertable).not.toRerender()
+ expect(assertable).toRenderExactlyTimes(3)
+ ```
+ */
+export type Assertable = {
+  [assertableSymbol]: RenderStream<any>;
+};
+
+export function markAssertable<T extends {}>(
+  assertable: T,
+  stream: RenderStream<any>
+): T & Assertable {
+  return Object.assign(assertable, {
+    [assertableSymbol]: stream,
+  });
+}

src/index.ts

@@ -0,0 +1,17 @@
+export type {
+  NextRenderOptions,
+  RenderStream,
+  RenderStreamWithRenderFn,
+} from "./profile/profile.js";
+export {
+  createRenderStream,
+  useTrackRenders,
+  WaitForRenderTimeoutError,
+} from "./profile/profile.js";
+
+export type { SyncScreen } from "./profile/Render.js";
+
+export { renderToRenderStream } from "./renderToRenderStream.js";
+export { renderHookToSnapshotStream } from "./renderHookToSnapshotStream.js";
+
+export type { Assertable } from "./assertable.js";

src/jest/ProfiledComponent.ts

@@ -1,19 +1,19 @@
 import type { MatcherFunction } from "expect";
 import { WaitForRenderTimeoutError } from "@testing-library/react-render-stream";
 import type {
+  Assertable,
   NextRenderOptions,
-  Profiler,
-  ProfiledComponent,
-  ProfiledHook,
+  RenderStream,
 } from "@testing-library/react-render-stream";
+// explicitly imported the symbol from the internal file
+// this will bundle the `Symbol.for` call twice, but we keep it private
+import { assertableSymbol } from "../assertable.js";
 
 export const toRerender: MatcherFunction<[options?: NextRenderOptions]> =
   async function (actual, options) {
-    const _profiler = actual as
-      | Profiler<any>
-      | ProfiledComponent<any, any>
-      | ProfiledHook<any, any>;
-    const profiler = "Profiler" in _profiler ? _profiler.Profiler : _profiler;
+    const _profiler = actual as RenderStream<any> | Assertable;
+    const profiler =
+      assertableSymbol in _profiler ? _profiler[assertableSymbol] : _profiler;
     const hint = this.utils.matcherHint("toRerender", "ProfiledComponent", "");
     let pass = true;
     try {
@@ -44,11 +44,9 @@ const failed = {};
 export const toRenderExactlyTimes: MatcherFunction<
   [times: number, options?: NextRenderOptions]
 > = async function (actual, times, optionsPerRender) {
-  const _profiler = actual as
-    | Profiler<any>
-    | ProfiledComponent<any, any>
-    | ProfiledHook<any, any>;
-  const profiler = "Profiler" in _profiler ? _profiler.Profiler : _profiler;
+  const _profiler = actual as RenderStream<any> | Assertable;
+  const profiler =
+    assertableSymbol in _profiler ? _profiler[assertableSymbol] : _profiler;
   const options = { timeout: 100, ...optionsPerRender };
   const hint = this.utils.matcherHint("toRenderExactlyTimes");
   let pass = true;

src/jest/index.ts

@@ -2,33 +2,30 @@ import { expect } from "@jest/globals";
 import { toRerender, toRenderExactlyTimes } from "./ProfiledComponent.js";
 import type {
   NextRenderOptions,
-  Profiler,
-  ProfiledComponent,
-  ProfiledHook,
-} from "../profile/index.js";
+  RenderStream,
+  Assertable,
+} from "@testing-library/react-render-stream";
 
 expect.extend({
   toRerender,
   toRenderExactlyTimes,
 });
-interface ApolloCustomMatchers<R = void, T = {}> {
-  toRerender: T extends
-    | Profiler<any>
-    | ProfiledComponent<any, any>
-    | ProfiledHook<any, any>
+interface CustomMatchers<R = void, T = {}> {
+  toRerender: T extends RenderStream<any> | Assertable
     ? (options?: NextRenderOptions) => Promise<R>
-    : { error: "matcher needs to be called on a ProfiledComponent instance" };
+    : {
+        error: "matcher needs to be called on a `takeRender` function, `takeSnapshot` function or `RenderStream` instance";
+      };
 
-  toRenderExactlyTimes: T extends
-    | Profiler<any>
-    | ProfiledComponent<any, any>
-    | ProfiledHook<any, any>
+  toRenderExactlyTimes: T extends RenderStream<any> | Assertable
     ? (count: number, options?: NextRenderOptions) => Promise<R>
-    : { error: "matcher needs to be called on a ProfiledComponent instance" };
+    : {
+        error: "matcher needs to be called on a `takeRender` function, `takeSnapshot` function or `RenderStream` instance";
+      };
 }
 
 declare global {
   namespace jest {
-    interface Matchers<R = void, T = {}> extends ApolloCustomMatchers<R, T> {}
+    interface Matchers<R = void, T = {}> extends CustomMatchers<R, T> {}
   }
 }

src/profile/Render.tsx

@@ -13,7 +13,6 @@ import { within, screen } from "@testing-library/dom";
 import { JSDOM, VirtualConsole } from "jsdom";
 import { applyStackTrace, captureStackTrace } from "./traces.js";
 
-/** @internal */
 export interface BaseRender {
   id: string;
   phase: "mount" | "update" | "nested-update";
@@ -28,7 +27,7 @@ export interface BaseRender {
 }
 
 type Screen = typeof screen;
-/** @internal */
+
 export type SyncScreen = {
   [K in keyof Screen]: K extends `find${string}`
     ? {
@@ -38,7 +37,6 @@ export type SyncScreen = {
     : Screen[K];
 };
 
-/** @internal */
 export interface Render<Snapshot> extends BaseRender {
   /**
    * The snapshot, as returned by the `takeSnapshot` option of `profile`.
@@ -66,7 +64,6 @@ export interface Render<Snapshot> extends BaseRender {
   renderedComponents: Array<string | React.ComponentType>;
 }
 
-/** @internal */
 export class RenderInstance<Snapshot> implements Render<Snapshot> {
   id: string;
   phase: "mount" | "update" | "nested-update";
@@ -138,7 +135,7 @@ export class RenderInstance<Snapshot> implements Render<Snapshot> {
     return () => snapScreen;
   }
 }
-/** @internal */
+
 export function errorOnDomInteraction() {
   const events: Array<keyof DocumentEventMap> = [
     "auxclick",