feather-testing-convex 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,353 @@
+# feather-testing-convex
+
+React provider that adapts [convex-test](https://www.npmjs.com/package/convex-test)'s one-shot query/mutation client for use with Convex's `ConvexProvider`, so `useQuery` and `useMutation` work in tests against an in-memory backend.
+
+## Install
+
+```bash
+npm i convex convex-test react
+npm i -D feather-testing-convex
+```
+
+## Quick Start
+
+Three files to get from zero to a working test:
+
+**1. `vitest.config.ts`**
+
+```typescript
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: "jsdom",
+    environmentMatchGlobs: [["convex/**", "edge-runtime"]],
+    server: { deps: { inline: ["convex-test"] } },
+    globals: true,
+    setupFiles: ["./src/test-setup.ts"],
+  },
+});
+```
+
+**2. `convex/test.setup.ts`**
+
+```typescript
+/// <reference types="vite/client" />
+import { createConvexTest, renderWithConvex } from "feather-testing-convex";
+import schema from "./schema";
+
+export const modules = import.meta.glob("./**/!(*.*.*)*.*s");
+export const test = createConvexTest(schema, modules);
+export { renderWithConvex };
+```
+
+**3. `src/test-setup.ts`**
+
+```typescript
+import "@testing-library/jest-dom/vitest";
+```
+
+**First test:**
+
+```tsx
+import { describe, expect } from "vitest";
+import { screen } from "@testing-library/react";
+import { test, renderWithConvex } from "../../convex/test.setup";
+import { TodoList } from "./TodoList";
+
+describe("TodoList", () => {
+  test("shows seeded data", async ({ client, seed }) => {
+    await seed("todos", { text: "Buy milk", completed: false });
+    renderWithConvex(<TodoList />, client);
+    expect(await screen.findByText("Buy milk")).toBeInTheDocument();
+  });
+});
+```
+
+For auth testing, see [Auth Testing](#auth-testing) below.
+
+## Usage
+
+> For the recommended setup, see [Quick Start](#quick-start) above. This section shows the low-level API.
+
+1. Create a convex-test client: `convexTest(schema, modules)`.
+2. Wrap your component with `ConvexTestProvider` and pass the client:
+
+```tsx
+import { convexTest } from "convex-test";
+import { ConvexTestProvider } from "feather-testing-convex";
+import schema from "./convex/schema";
+import { modules } from "./convex/test.setup";
+
+const testClient = convexTest(schema, modules);
+
+render(
+  <ConvexTestProvider client={testClient}>
+    <YourComponent />
+  </ConvexTestProvider>
+);
+```
+
+## Query reactivity
+
+This adapter runs each query **once** (when the component mounts). The UI does not re-render after a mutation in the same test. Assert backend state via `client.query(api.your.list, {})`, or re-mount to run the query again.
+
+## Helper Functions
+
+Reduce test boilerplate from ~15 lines to ~2 lines with `createConvexTest`.
+
+### Setup
+
+Create a test setup file in your Convex directory:
+
+```typescript
+// convex/test.setup.ts
+import { createConvexTest, renderWithConvex } from "feather-testing-convex";
+import schema from "./schema";
+
+export const modules = import.meta.glob("./**/!(*.*.*)*.*s");
+export const test = createConvexTest(schema, modules);
+export { renderWithConvex };
+```
+
+### Usage
+
+```typescript
+// src/components/TodoList.test.tsx
+import { test, renderWithConvex } from "../../convex/test.setup";
+import { expect } from "vitest";
+import { api } from "../../convex/_generated/api";
+
+test("creates a todo", async ({ client, seed }) => {
+  await seed("todos", { text: "Buy milk", completed: false });
+
+  const todos = await client.query(api.todos.list, {});
+  expect(todos).toHaveLength(1);
+});
+```
+
+### Fixtures
+
+| Fixture | Description |
+|---------|-------------|
+| `testClient` | Raw convex-test client (unauthenticated) |
+| `userId` | ID of an auto-created user (string) |
+| `client` | Authenticated client for the auto-created user |
+| `seed(table, data)` | Insert a document. Auto-fills `userId` unless `data` includes an explicit `userId` (explicit wins). Returns the document ID. |
+| `createUser()` | Create another user, return authenticated client with `.userId` property. |
+
+### Multi-user Test Example
+
+```typescript
+test("users only see their own todos", async ({ client, seed, createUser }) => {
+  // Alice creates a todo
+  await client.mutation(api.todos.create, { text: "Alice's todo" });
+
+  // Bob creates a todo (seed with explicit userId)
+  const bob = await createUser();
+  await seed("todos", { text: "Bob's todo", completed: false, userId: bob.userId });
+
+  // Each user only sees their own
+  const aliceTodos = await client.query(api.todos.list, {});
+  expect(aliceTodos).toHaveLength(1);
+
+  const bobTodos = await bob.query(api.todos.list, {});
+  expect(bobTodos).toHaveLength(1);
+  expect(bobTodos[0].text).toBe("Bob's todo");
+});
+```
+
+### Configuration
+
+```typescript
+// Custom users table name
+export const test = createConvexTest(schema, modules, {
+  usersTable: "profiles",
+});
+```
+
+### Additional Helpers
+
+- `wrapWithConvex(children, client)` — JSX wrapper for custom rendering
+- `renderWithConvex(ui, client)` — Testing Library render with Convex provider
+
+## Auth Testing
+
+Test components that use `<Authenticated>`, `<Unauthenticated>`, `useConvexAuth()`, and `useAuthActions()` — without mocking.
+
+### Prerequisites
+
+```bash
+npm i -D @convex-dev/auth
+```
+
+Add the vitest plugin to resolve an internal `@convex-dev/auth` import ([upstream fix requested](https://github.com/get-convex/convex-auth/issues/281)):
+
+```typescript
+// vitest.config.ts
+import { convexTestProviderPlugin } from "feather-testing-convex/vitest-plugin";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    convexTestProviderPlugin(),  // resolves @convex-dev/auth internal import
+  ],
+  // ... rest of config unchanged
+});
+```
+
+### Usage
+
+```tsx
+import { renderWithConvexAuth } from "feather-testing-convex";
+
+// Authenticated (default) — <Authenticated> children render
+renderWithConvexAuth(<App />, client);
+
+// Unauthenticated — <Unauthenticated> children render
+renderWithConvexAuth(<App />, client, { authenticated: false });
+```
+
+`renderWithConvexAuth` wraps your component with both auth state (so `<Authenticated>`, `<Unauthenticated>`, and `useConvexAuth()` work) and auth actions context (so `useAuthActions()` works). Calling `signIn()` sets auth to true; calling `signOut()` sets auth to false — the view re-renders accordingly.
+
+### Complete auth test example
+
+```tsx
+import { test, renderWithConvexAuth } from "../../convex/test.setup";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { expect } from "vitest";
+
+test("sign out toggles the view", async ({ client }) => {
+  const user = userEvent.setup();
+  renderWithConvexAuth(<App />, client);
+
+  await user.click(screen.getByRole("button", { name: /sign out/i }));
+  expect(await screen.findByText("Please sign in")).toBeInTheDocument();
+});
+```
+
+### Sign-in error simulation
+
+```tsx
+renderWithConvexAuth(<App />, client, {
+  authenticated: false,
+  signInError: new Error("Invalid credentials"),
+});
+```
+
+### Direct `ConvexTestAuthProvider` (custom wrapping)
+
+```tsx
+import { ConvexTestAuthProvider } from "feather-testing-convex";
+
+<ConvexTestAuthProvider client={client} authenticated={true}>
+  <YourComponent />
+</ConvexTestAuthProvider>
+```
+
+## Vitest Configuration Reference
+
+### Minimal config (no auth)
+
+```typescript
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: "jsdom",
+    environmentMatchGlobs: [["convex/**", "edge-runtime"]],
+    server: { deps: { inline: ["convex-test"] } },
+    globals: true,
+    setupFiles: ["./src/test-setup.ts"],
+  },
+});
+```
+
+### With auth testing
+
+```typescript
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+import { convexTestProviderPlugin } from "feather-testing-convex/vitest-plugin";
+
+export default defineConfig({
+  plugins: [react(), convexTestProviderPlugin()],
+  test: {
+    environment: "jsdom",
+    environmentMatchGlobs: [["convex/**", "edge-runtime"]],
+    server: { deps: { inline: ["convex-test"] } },
+    globals: true,
+    setupFiles: ["./src/test-setup.ts"],
+  },
+});
+```
+
+### Config options explained
+
+| Option | Why |
+|--------|-----|
+| `react()` | JSX transform for test files |
+| `environment: "jsdom"` | DOM APIs for React component tests |
+| `environmentMatchGlobs` | Convex functions run in edge runtime, not jsdom |
+| `server.deps.inline: ["convex-test"]` | convex-test must be inlined for Vitest to resolve it |
+| `setupFiles` | Load jest-dom matchers (`toBeInTheDocument()`, etc.) |
+| `convexTestProviderPlugin()` | Resolves `@convex-dev/auth` internal import (auth testing only) |
+
+## Agent Skills
+
+Install skills for AI coding agents via [skills.sh](https://skills.sh):
+
+```bash
+npx skills add siraj-samsudeen/feather-testing-convex
+```
+
+This installs three skills: `setup-convex-testing`, `add-convex-auth-testing`, and `convex-test-patterns`.
+
+## Limitations
+
+### One-shot query execution (non-reactive)
+
+Queries resolve **once** at component mount. After a mutation, the UI does not automatically re-render with updated data — this adapter does not simulate Convex's reactive subscription model.
+
+To verify backend state after a mutation, query directly:
+
+```tsx
+await user.click(screen.getByRole("button", { name: "Add" }));
+const items = await client.query(api.items.list, {});
+expect(items).toHaveLength(1);
+```
+
+To see updated data in the UI, unmount and remount the component (or call `rerender`).
+
+### Nested `runQuery`/`runMutation` lose auth context
+
+When a Convex function calls `ctx.runQuery()` or `ctx.runMutation()`, the nested call does not inherit the caller's auth identity. This is an [upstream limitation in convex-test](https://github.com/get-convex/convex-test) ([issue #50](https://github.com/get-convex/convex-test/issues/50)), not in this package.
+
+**Root cause:** In `convex-test`, the `queryFromPath` and `mutationFromPath` handlers spread `{ ...ctx, auth }` but do not override `ctx.runQuery`/`ctx.runMutation` with auth-aware versions. Actions (`actionFromPath`) already do this correctly.
+
+**Workarounds:**
+
+1. **Pass userId as an explicit argument** (recommended) — create `internalQuery`/`internalMutation` variants that accept `userId` instead of reading `ctx.auth.getUserIdentity()` inside nested calls.
+2. **Use `patch-package`** — apply a 2-line fix to `node_modules/convex-test/dist/index.js`:
+   - In `queryFromPath`: change `{ ...ctx, auth }` to `{ ...ctx, auth, runQuery: byType.query }`
+   - In `runTransaction`: change `{ ...ctx, auth, ...extraCtx }` to `{ ...ctx, auth, runQuery: byType.query, runMutation: byType.mutation, ...extraCtx }`
+3. **Use actions for orchestration** — actions already propagate auth correctly to nested calls (note: different transactional semantics).
+
+## Types
+
+The `client` prop accepts any object with `query(ref, args)` and `mutation(ref, args)` returning promises. The result of `convexTest(schema, modules)` (and `.withIdentity(...)`) satisfies this.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow.
+
+AI agents: See [CLAUDE.md](CLAUDE.md) for quick reference.
+
+## Versioning
+
+Releases follow [semantic versioning](https://semver.org/). See [CHANGELOG.md](./CHANGELOG.md) for release history.

package/dist/ConvexTestAuthProvider.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from "react";
+import { type ConvexTestClient } from "./ConvexTestProvider.js";
+/**
+ * Wraps children with both auth state (ConvexProviderWithAuth) and auth actions
+ * (ConvexAuthActionsContext), so components using <Authenticated>, <Unauthenticated>,
+ * useConvexAuth(), and useAuthActions() all work in tests.
+ *
+ * signIn/signOut are pure React state toggles — no backend calls.
+ * For auth-dependent queries, use `client.withIdentity()` to inject identity
+ * so `getAuthUserId(ctx)` returns a valid user ID.
+ */
+export declare function ConvexTestAuthProvider({ client, children, authenticated, signInError, }: {
+    client: ConvexTestClient;
+    children: ReactNode;
+    authenticated?: boolean;
+    /** When set, signIn() rejects with this error instead of toggling state. */
+    signInError?: Error;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ConvexTestAuthProvider.d.ts.map

package/dist/ConvexTestAuthProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvexTestAuthProvider.d.ts","sourceRoot":"","sources":["../src/ConvexTestAuthProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAKjD,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEpF;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,MAAM,EACN,QAAQ,EACR,aAAoB,EACpB,WAAW,GACZ,EAAE;IACD,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,KAAK,CAAC;CACrB,2CAqBA"}

package/dist/ConvexTestAuthProvider.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// TODO: Replace with public export when @convex-dev/auth provides one.
+// Track: https://github.com/get-convex/convex-auth — request exported TestAuthProvider or context.
+import { useState } from "react";
+// @ts-expect-error — internal path not in package exports; works at runtime via bundler
+import { ConvexAuthActionsContext } from "@convex-dev/auth/dist/react/client.js";
+import { ConvexTestProvider } from "./ConvexTestProvider.js";
+/**
+ * Wraps children with both auth state (ConvexProviderWithAuth) and auth actions
+ * (ConvexAuthActionsContext), so components using <Authenticated>, <Unauthenticated>,
+ * useConvexAuth(), and useAuthActions() all work in tests.
+ *
+ * signIn/signOut are pure React state toggles — no backend calls.
+ * For auth-dependent queries, use `client.withIdentity()` to inject identity
+ * so `getAuthUserId(ctx)` returns a valid user ID.
+ */
+export function ConvexTestAuthProvider({ client, children, authenticated = true, signInError, }) {
+    const [isAuth, setIsAuth] = useState(authenticated);
+    const actions = {
+        signIn: async () => {
+            if (signInError)
+                throw signInError;
+            setIsAuth(true);
+            return { signingIn: false };
+        },
+        signOut: async () => {
+            setIsAuth(false);
+        },
+    };
+    return (_jsx(ConvexTestProvider, { client: client, authenticated: isAuth, children: _jsx(ConvexAuthActionsContext.Provider, { value: actions, children: children }) }));
+}

package/dist/ConvexTestProvider.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+/** Minimal client shape: one-shot query, mutation, action, plus identity injection. Matches convex-test client. */
+export interface ConvexTestClient {
+    query: (query: unknown, args: unknown) => Promise<unknown>;
+    mutation: (mutation: unknown, args: unknown) => Promise<unknown>;
+    action: (action: unknown, args: unknown) => Promise<unknown>;
+    run: (fn: (ctx: any) => Promise<any>) => Promise<any>;
+    withIdentity: (identity: Record<string, unknown>) => ConvexTestClient;
+}
+/**
+ * Wraps children in ConvexProvider with a fake client that adapts convex-test's
+ * one-shot query/mutation API to the reactive watchQuery API the real ConvexProvider expects.
+ * Lets useQuery/useMutation run in tests against an in-memory backend.
+ *
+ * When `authenticated` is provided, uses ConvexProviderWithAuth instead of ConvexProvider,
+ * enabling <Authenticated>, <Unauthenticated>, and useConvexAuth() in tested components.
+ */
+export declare function ConvexTestProvider({ client, children, authenticated, }: {
+    client: ConvexTestClient;
+    children: ReactNode;
+    authenticated?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ConvexTestProvider.d.ts.map

package/dist/ConvexTestProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvexTestProvider.d.ts","sourceRoot":"","sources":["../src/ConvexTestProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGrE,mHAAmH;AACnH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3D,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACtD,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,gBAAgB,CAAC;CACvE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,QAAQ,EACR,aAAa,GACd,EAAE;IACD,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,2CA2EA"}

package/dist/ConvexTestProvider.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef } from "react";
+import { ConvexProvider, ConvexProviderWithAuth } from "convex/react";
+/**
+ * Wraps children in ConvexProvider with a fake client that adapts convex-test's
+ * one-shot query/mutation API to the reactive watchQuery API the real ConvexProvider expects.
+ * Lets useQuery/useMutation run in tests against an in-memory backend.
+ *
+ * When `authenticated` is provided, uses ConvexProviderWithAuth instead of ConvexProvider,
+ * enabling <Authenticated>, <Unauthenticated>, and useConvexAuth() in tested components.
+ */
+export function ConvexTestProvider({ client, children, authenticated, }) {
+    // Two-level cache: query reference identity → serialized args → result.
+    // Avoids collisions between different query functions whose proxies all
+    // stringify to "{}" (see issue #2). Approach from PR #3.
+    // useRef so cache survives re-renders (e.g. auth state toggle).
+    const cache = useRef(new Map());
+    // Ref for authenticated so fakeClient.setAuth reads the latest value
+    // without needing authenticated in the useMemo dependency array.
+    const authenticatedRef = useRef(authenticated);
+    authenticatedRef.current = authenticated;
+    // Stable reference — only changes when the client prop itself changes.
+    // ConvexProviderWithAuth puts client in useEffect deps; an unstable
+    // reference would trigger setAuth/clearAuth cycles every render.
+    const fakeClient = useMemo(() => ({
+        watchQuery: (query, args) => {
+            let queryCache = cache.current.get(query);
+            if (!queryCache) {
+                queryCache = new Map();
+                cache.current.set(query, queryCache);
+            }
+            const argsKey = JSON.stringify(args ?? {});
+            let subscriber = null;
+            client.query(query, args ?? {}).then((result) => {
+                queryCache.set(argsKey, result);
+                subscriber?.();
+            });
+            return {
+                localQueryResult: () => queryCache.get(argsKey),
+                onUpdate: (cb) => {
+                    subscriber = cb;
+                    return () => { subscriber = null; };
+                },
+            };
+        },
+        mutation: (mutation, args) => {
+            return client.mutation(mutation, args ?? {});
+        },
+        // Synchronous — real client calls onChange async, but ConvexProviderWithAuth
+        // calls setAuth inside useEffect (committed state), so sync is safe here.
+        setAuth: (_fetchToken, onChange) => {
+            onChange(authenticatedRef.current ?? false);
+        },
+        clearAuth: () => { },
+    }), [client]);
+    // Stable fetchAccessToken — ConvexProviderWithAuth puts this in useEffect
+    // deps. Unstable reference would trigger setAuth/clearAuth every render,
+    // pausing/resuming websockets. Matches Convex's own Auth0 provider pattern.
+    const fetchAccessToken = useCallback(async () => null, []);
+    // Only changes when authenticated changes — which is when we actually
+    // want ConvexProviderWithAuth to re-run its auth effects.
+    const useAuth = useCallback(() => ({
+        isLoading: false,
+        isAuthenticated: authenticated ?? false,
+        fetchAccessToken,
+    }), [authenticated, fetchAccessToken]);
+    if (authenticated === undefined) {
+        return (_jsx(ConvexProvider, { client: fakeClient, children: children }));
+    }
+    return (_jsx(ConvexProviderWithAuth, { client: fakeClient, useAuth: useAuth, children: children }));
+}

package/dist/helpers.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode, ReactElement } from "react";
+interface CreateConvexTestOptions {
+    usersTable?: string;
+}
+export declare function createConvexTest(schema: any, modules: any, options?: CreateConvexTestOptions): import("vitest").TestAPI<{
+    client: any;
+    testClient: any;
+    userId: string;
+    seed: (table: string, data: Record<string, unknown>) => Promise<string>;
+    createUser: () => Promise<any & {
+        userId: string;
+    }>;
+}>;
+export declare function wrapWithConvex(children: ReactNode, client: unknown): import("react/jsx-runtime").JSX.Element;
+export declare function renderWithConvex(ui: ReactElement, client: unknown): import("@testing-library/react").RenderResult<typeof import("@testing-library/dom/types/queries.js"), HTMLElement, HTMLElement>;
+export declare function renderWithConvexAuth(ui: ReactElement, client: unknown, options?: {
+    authenticated?: boolean;
+    signInError?: Error;
+}): import("@testing-library/react").RenderResult<typeof import("@testing-library/dom/types/queries.js"), HTMLElement, HTMLElement>;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAErD,UAAU,uBAAuB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAaD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,GAAG,EACX,OAAO,EAAE,GAAG,EACZ,OAAO,GAAE,uBAA4B;;;;kBAVvB,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC;sBACrD,OAAO,CAAC,GAAG,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;GA4CpD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,2CAElE;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,mIAIjE;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,mIAa3D"}

package/dist/helpers.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { test as baseTest } from "vitest";
+import { convexTest } from "convex-test";
+import { ConvexTestProvider } from "./ConvexTestProvider.js";
+import { ConvexTestAuthProvider } from "./ConvexTestAuthProvider.js";
+import { render } from "@testing-library/react";
+const dbInsert = (client, table, data) => client.run((ctx) => ctx.db.insert(table, data));
+export function createConvexTest(schema, modules, options = {}) {
+    const usersTable = options.usersTable ?? "users";
+    return baseTest.extend({
+        testClient: async ({}, use) => {
+            const client = convexTest(schema, modules);
+            await use(client);
+        },
+        userId: async ({ testClient }, use) => {
+            const id = await dbInsert(testClient, usersTable, {});
+            await use(id);
+        },
+        client: async ({ testClient, userId }, use) => {
+            const authenticated = testClient.withIdentity({ subject: userId });
+            await use(authenticated);
+        },
+        seed: async ({ testClient, userId }, use) => {
+            const seedFn = (table, data) => dbInsert(testClient, table, { userId, ...data });
+            await use(seedFn);
+        },
+        createUser: async ({ testClient }, use) => {
+            const createUserFn = async () => {
+                const newUserId = await dbInsert(testClient, usersTable, {});
+                const userClient = testClient.withIdentity({ subject: newUserId });
+                return Object.assign(userClient, { userId: newUserId });
+            };
+            await use(createUserFn);
+        },
+    });
+}
+export function wrapWithConvex(children, client) {
+    return _jsx(ConvexTestProvider, { client: client, children: children });
+}
+export function renderWithConvex(ui, client) {
+    return render(ui, {
+        wrapper: ({ children }) => wrapWithConvex(children, client),
+    });
+}
+export function renderWithConvexAuth(ui, client, options) {
+    return render(ui, {
+        wrapper: ({ children }) => (_jsx(ConvexTestAuthProvider, { client: client, authenticated: options?.authenticated ?? true, signInError: options?.signInError, children: children })),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ConvexTestProvider, type ConvexTestClient } from "./ConvexTestProvider.js";
+export { ConvexTestAuthProvider } from "./ConvexTestAuthProvider.js";
+export { createConvexTest, wrapWithConvex, renderWithConvex, renderWithConvexAuth, } from "./helpers.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ConvexTestProvider } from "./ConvexTestProvider.js";
+export { ConvexTestAuthProvider } from "./ConvexTestAuthProvider.js";
+export { createConvexTest, wrapWithConvex, renderWithConvex, renderWithConvexAuth, } from "./helpers.js";

package/dist/vitest-plugin.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Vite plugin that resolves the internal @convex-dev/auth import used by
+ * ConvexTestAuthProvider. Add this to your vitest.config.ts plugins array
+ * so you don't need a manual resolve.alias entry.
+ *
+ * Background: ConvexTestAuthProvider imports ConvexAuthActionsContext from
+ * @convex-dev/auth/dist/react/client.js — an internal path not in the
+ * package's exports field. Vite enforces exports strictly and blocks it.
+ * This plugin adds a resolve.alias so Vite can find the file.
+ *
+ * Upstream fix requested: https://github.com/get-convex/convex-auth/issues/281
+ *
+ * @example
+ * ```ts
+ * import { convexTestProviderPlugin } from "feather-testing-convex/vitest-plugin";
+ *
+ * export default defineConfig({
+ *   plugins: [convexTestProviderPlugin()],
+ * });
+ * ```
+ */
+export declare function convexTestProviderPlugin(): {
+    name: string;
+    config(): {
+        resolve: {
+            alias: {
+                "@convex-dev/auth/dist/react/client.js": string;
+            };
+        };
+    };
+};
+//# sourceMappingURL=vitest-plugin.d.ts.map

package/dist/vitest-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest-plugin.d.ts","sourceRoot":"","sources":["../src/vitest-plugin.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB;;;;;;;;;EA2BvC"}

package/dist/vitest-plugin.js

@@ -0,0 +1,47 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+/**
+ * Vite plugin that resolves the internal @convex-dev/auth import used by
+ * ConvexTestAuthProvider. Add this to your vitest.config.ts plugins array
+ * so you don't need a manual resolve.alias entry.
+ *
+ * Background: ConvexTestAuthProvider imports ConvexAuthActionsContext from
+ * @convex-dev/auth/dist/react/client.js — an internal path not in the
+ * package's exports field. Vite enforces exports strictly and blocks it.
+ * This plugin adds a resolve.alias so Vite can find the file.
+ *
+ * Upstream fix requested: https://github.com/get-convex/convex-auth/issues/281
+ *
+ * @example
+ * ```ts
+ * import { convexTestProviderPlugin } from "feather-testing-convex/vitest-plugin";
+ *
+ * export default defineConfig({
+ *   plugins: [convexTestProviderPlugin()],
+ * });
+ * ```
+ */
+export function convexTestProviderPlugin() {
+    // require.resolve("@convex-dev/auth/dist/react/client.js") throws
+    // ERR_PACKAGE_PATH_NOT_EXPORTED because the path isn't in exports.
+    // Resolve from the consumer's project root (not from this plugin's
+    // location) so the alias points to the same copy that useAuthActions()
+    // uses — avoiding React Context duplication.
+    const require = createRequire(resolve(process.cwd(), "package.json"));
+    const mainEntry = require.resolve("@convex-dev/auth/react");
+    const pkgName = "@convex-dev/auth";
+    const authRoot = mainEntry.slice(0, mainEntry.indexOf(pkgName) + pkgName.length);
+    const resolved = resolve(authRoot, "dist/react/client.js");
+    return {
+        name: "feather-testing-convex",
+        config() {
+            return {
+                resolve: {
+                    alias: {
+                        "@convex-dev/auth/dist/react/client.js": resolved,
+                    },
+                },
+            };
+        },
+    };
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "feather-testing-convex",
+  "version": "0.4.0",
+  "description": "React provider that adapts convex-test's one-shot client for use with ConvexProvider, so useQuery/useMutation work in tests.",
+  "license": "MIT",
+  "keywords": [
+    "convex",
+    "testing",
+    "react",
+    "provider",
+    "convex-test"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siraj-samsudeen/feather-testing-convex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/siraj-samsudeen/feather-testing-convex/issues"
+  },
+  "homepage": "https://github.com/siraj-samsudeen/feather-testing-convex#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./vitest-plugin": {
+      "types": "./dist/vitest-plugin.d.ts",
+      "import": "./dist/vitest-plugin.js",
+      "default": "./dist/vitest-plugin.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@convex-dev/auth": ">=0.0.80",
+    "@testing-library/react": ">=14.0.0",
+    "convex": ">=1.0.0",
+    "convex-test": ">=0.0.1",
+    "react": ">=18.0.0",
+    "vitest": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@testing-library/react": {
+      "optional": true
+    },
+    "@convex-dev/auth": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@convex-dev/auth": "^0.0.90",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.10",
+    "@vitejs/plugin-react": "^5.1.3",
+    "convex": "^1.31.7",
+    "convex-test": "^0.0.41",
+    "jsdom": "^28.0.0",
+    "react": "^19.2.4",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.18"
+  }
+}