@forthtilliath/expo-test-kit 0.3.1 → 0.4.1

package/README.md

@@ -1,11 +1,13 @@
 # @forthtilliath/expo-test-kit
 
-Test helpers for Expo/Drizzle apps: a real in-memory SQLite database (via libsql) to exercise a Drizzle repository's actual SQL, and a lightweight `expo-file-system` fake — both extracted from patterns that were duplicated across test files rather than shared.
+Test helpers for Expo/Drizzle apps: a real in-memory SQLite database (via libsql) to exercise a Drizzle repository's actual SQL, a lightweight `expo-file-system` fake, and a whole-app renderer for Expo Router — all extracted from patterns that were duplicated across test files rather than shared.
 
 ## Install
 
 ```bash
-npm install --save-dev @forthtilliath/expo-test-kit drizzle-orm @libsql/client
+npm install --save-dev @forthtilliath/expo-test-kit
+# only for the sqlite/ helpers:
+npm install --save-dev drizzle-orm @libsql/client
 ```
 
 Or, from within this monorepo, as a workspace dependency:
@@ -18,7 +20,7 @@ Or, from within this monorepo, as a workspace dependency:
 }
 ```
 
-`drizzle-orm` and `@libsql/client` are peer dependencies — install them if not already present. Both are dev-only: `expo-test-kit` doesn't touch your app's production `expo-sqlite` driver, it's a separate in-memory database used only while testing.
+`drizzle-orm` and `@libsql/client` are **optional** peer dependencies: only the `sqlite/` modules need them, so an app that only takes `router/createRenderApp` or the file-system fake doesn't install them. Both are dev-only: `expo-test-kit` doesn't touch your app's production `expo-sqlite` driver, it's a separate in-memory database used only while testing.
 
 ## Usage
 
@@ -28,6 +30,7 @@ has an obvious home instead of piling into one flat `src/`:
 
 - `sqlite/` — the SQLite/Drizzle/libsql test database and its mocking helper.
 - `file-system/` — the `expo-file-system` fake.
+- `router/` — whole-app rendering through Expo Router.
 
 ```ts
 import {
@@ -95,6 +98,35 @@ beforeAll(() => {
 });
 ```
 
+### `createRenderApp(deps, options?)`
+
+Builds a `renderApp(initialUrl)` that renders the whole app — the real screens of `app/`, the real Expo Router navigation — from a URL, and returns `{ getPathname, getSearchParams, navigate }`. It settles the two traps of `renderRouter` under Testing Library v14: fake timers are advanced _before_ awaiting the render (`renderRouter` turns them on, and the first async render never ends otherwise), and a plain object is returned rather than the enriched promise. `navigate` runs inside `act` and waits for the render.
+
+Expo Router, its testing library and the test runner are passed in (`deps`), so this package depends on none of them. `options`: `appDir` (`"./app"`), `settleMs` (`100`).
+
+```ts
+// test/renderApp.ts
+import { router } from "expo-router";
+import { act, renderRouter } from "expo-router/testing-library";
+import { createRenderApp } from "@forthtilliath/expo-test-kit/router/createRenderApp";
+
+export const renderApp = createRenderApp({
+  renderRouter,
+  act,
+  navigate: (path) => {
+    router.navigate(path);
+  },
+  advanceTimersByTimeAsync: (ms) => jest.advanceTimersByTimeAsync(ms),
+});
+
+// in a test
+const app = await renderApp("/games/new");
+await app.navigate("/settings");
+expect(app.getPathname()).toBe("/settings");
+```
+
+For Zustand stores persisted in `AsyncStorage`, see `readPersisted` / `writePersisted` in `@forthtilliath/test-kit`.
+
 ## Scripts
 
 ```bash

package/dist/router/createRenderApp.d.ts

@@ -0,0 +1,63 @@
+interface RenderedRouter<SearchParams> {
+    getPathname: () => string;
+    getSearchParams: () => SearchParams;
+}
+export interface RenderAppDeps<SearchParams> {
+    /** `renderRouter` from `expo-router/testing-library`. */
+    renderRouter: (appDir: string, options: {
+        initialUrl: string;
+    }) => PromiseLike<RenderedRouter<SearchParams>>;
+    /** `act` from `expo-router/testing-library`. */
+    act: (callback: () => Promise<void>) => PromiseLike<unknown>;
+    /** Navigates like the app does: `(path) => { router.navigate(path); }`. */
+    navigate: (path: string) => unknown;
+    /** `jest.advanceTimersByTimeAsync` or `vi.advanceTimersByTimeAsync`. */
+    advanceTimersByTimeAsync: (ms: number) => PromiseLike<unknown>;
+}
+export interface RenderAppOptions {
+    /** The routes folder, relative to the test runner's root. @defaultValue "./app" */
+    appDir?: string;
+    /** Fake time advanced for the first render to settle. @defaultValue 100 */
+    settleMs?: number;
+}
+/**
+ * Builds a `renderApp(initialUrl)` that renders the whole app — the real
+ * screens of `app/`, the real Expo Router navigation — from a URL.
+ *
+ * Settles the two traps of `renderRouter` under Testing Library v14:
+ * it turns fake timers on, so they must be advanced *before* awaiting the
+ * render, or the first async render never ends; and what it returns is an
+ * enriched promise, so `renderApp` hands back a plain object instead.
+ * `navigate` waits for the render (`testRouter` checks the path right
+ * after navigating, without waiting).
+ *
+ * Expo Router, its testing library and the test runner are passed in, so
+ * this package depends on none of them.
+ *
+ * @example
+ * ```ts
+ * // test/renderApp.ts
+ * import { router } from "expo-router";
+ * import { act, renderRouter } from "expo-router/testing-library";
+ * import { createRenderApp } from "@forthtilliath/expo-test-kit/router/createRenderApp";
+ *
+ * export const renderApp = createRenderApp({
+ *   renderRouter,
+ *   act,
+ *   navigate: (path) => { router.navigate(path); },
+ *   advanceTimersByTimeAsync: (ms) => jest.advanceTimersByTimeAsync(ms),
+ * });
+ *
+ * // in a test
+ * const app = await renderApp("/games/new");
+ * await app.navigate("/settings");
+ * expect(app.getPathname()).toBe("/settings");
+ * ```
+ */
+export declare function createRenderApp<SearchParams>(deps: RenderAppDeps<SearchParams>, { appDir, settleMs }?: RenderAppOptions): (initialUrl: string) => Promise<{
+    getPathname: () => string;
+    getSearchParams: () => SearchParams;
+    navigate: (path: string) => Promise<void>;
+}>;
+export {};
+//# sourceMappingURL=createRenderApp.d.ts.map

package/dist/router/createRenderApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createRenderApp.d.ts","sourceRoot":"","sources":["../../src/router/createRenderApp.ts"],"names":[],"mappings":"AAEA,UAAU,cAAc,CAAC,YAAY;IACnC,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,YAAY,CAAC;CACrC;AAED,MAAM,WAAW,aAAa,CAAC,YAAY;IACzC,yDAAyD;IACzD,YAAY,EAAE,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,KAC5B,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC;IAC/C,gDAAgD;IAChD,GAAG,EAAE,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7D,2EAA2E;IAC3E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC,wEAAwE;IACxE,wBAAwB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,WAAW,CAAC,OAAO,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAC1C,IAAI,EAAE,aAAa,CAAC,YAAY,CAAC,EACjC,EAAE,MAAgB,EAAE,QAAc,EAAE,GAAE,gBAAqB,IAE3B,YAAY,MAAM;;;qBAOvB,MAAM;GASlC"}

package/dist/router/createRenderApp.js

@@ -0,0 +1,52 @@
+/**
+ * Builds a `renderApp(initialUrl)` that renders the whole app — the real
+ * screens of `app/`, the real Expo Router navigation — from a URL.
+ *
+ * Settles the two traps of `renderRouter` under Testing Library v14:
+ * it turns fake timers on, so they must be advanced *before* awaiting the
+ * render, or the first async render never ends; and what it returns is an
+ * enriched promise, so `renderApp` hands back a plain object instead.
+ * `navigate` waits for the render (`testRouter` checks the path right
+ * after navigating, without waiting).
+ *
+ * Expo Router, its testing library and the test runner are passed in, so
+ * this package depends on none of them.
+ *
+ * @example
+ * ```ts
+ * // test/renderApp.ts
+ * import { router } from "expo-router";
+ * import { act, renderRouter } from "expo-router/testing-library";
+ * import { createRenderApp } from "@forthtilliath/expo-test-kit/router/createRenderApp";
+ *
+ * export const renderApp = createRenderApp({
+ *   renderRouter,
+ *   act,
+ *   navigate: (path) => { router.navigate(path); },
+ *   advanceTimersByTimeAsync: (ms) => jest.advanceTimersByTimeAsync(ms),
+ * });
+ *
+ * // in a test
+ * const app = await renderApp("/games/new");
+ * await app.navigate("/settings");
+ * expect(app.getPathname()).toBe("/settings");
+ * ```
+ */
+export function createRenderApp(deps, { appDir = "./app", settleMs = 100 } = {}) {
+    return async function renderApp(initialUrl) {
+        const rendering = deps.renderRouter(appDir, { initialUrl });
+        await deps.advanceTimersByTimeAsync(settleMs);
+        const app = await rendering;
+        return {
+            getPathname: () => app.getPathname(),
+            getSearchParams: () => app.getSearchParams(),
+            navigate: async (path) => {
+                // Un callback qui renvoie une promesse : act attend la fin du rendu.
+                await deps.act(() => {
+                    deps.navigate(path);
+                    return Promise.resolve();
+                });
+            },
+        };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/expo-test-kit",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -23,6 +23,14 @@
     "@libsql/client": ">=0.14.0",
     "drizzle-orm": ">=0.44.0"
   },
+  "peerDependenciesMeta": {
+    "@libsql/client": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@libsql/client": "^0.17.4",
     "@types/node": "^26.2.0",
@@ -30,7 +38,7 @@
     "eslint": "10.7.0",
     "typescript": "^5.9.3",
     "vitest": "^5.0.2",
-    "@forthtilliath/eslint-config": "0.8.0",
+    "@forthtilliath/eslint-config": "0.9.0",
     "@forthtilliath/typescript-config": "0.1.1"
   },
   "scripts": {