create-miden-app 1.0.4 → 1.0.7

package/template/src/__tests__/mocks/miden-sdk-react.ts

@@ -0,0 +1,261 @@
+/**
+ * Mock module for @miden-sdk/react.
+ *
+ * Usage in test files:
+ *
+ *   vi.mock('@miden-sdk/react', () => import('@/__tests__/mocks/miden-sdk-react'));
+ *
+ * Override specific hooks in individual tests:
+ *
+ *   import { useAccounts } from '@miden-sdk/react';
+ *   vi.mocked(useAccounts).mockReturnValue({ wallets: [], ... });
+ */
+
+import { vi } from "vitest";
+import {
+  MOCK_WALLET_HEADER,
+  MOCK_WALLET_HEADER_2,
+  MOCK_FAUCET_HEADER,
+  MOCK_ACCOUNT,
+  MOCK_ASSET_BALANCE,
+  MOCK_ASSET_METADATA,
+  MOCK_INPUT_NOTE_RECORD,
+  MOCK_CONSUMABLE_NOTE_RECORD,
+  MOCK_NOTE_SUMMARY,
+  MOCK_TRANSACTION_RESULT,
+  MOCK_SEND_RESULT,
+  FAUCET_ID,
+} from "../fixtures";
+
+// ---------------------------------------------------------------------------
+// Query hooks
+// ---------------------------------------------------------------------------
+
+export const useAccounts = vi.fn(() => ({
+  accounts: [MOCK_WALLET_HEADER, MOCK_WALLET_HEADER_2, MOCK_FAUCET_HEADER],
+  wallets: [MOCK_WALLET_HEADER, MOCK_WALLET_HEADER_2],
+  faucets: [MOCK_FAUCET_HEADER],
+  isLoading: false,
+  error: null,
+  refetch: vi.fn(),
+}));
+
+export const useAccount = vi.fn(() => ({
+  account: MOCK_ACCOUNT,
+  assets: [MOCK_ASSET_BALANCE],
+  isLoading: false,
+  error: null,
+  refetch: vi.fn(),
+  getBalance: vi.fn((assetId: string) =>
+    assetId === FAUCET_ID ? MOCK_ASSET_BALANCE.amount : 0n,
+  ),
+}));
+
+export const useNotes = vi.fn(() => ({
+  notes: [MOCK_INPUT_NOTE_RECORD],
+  consumableNotes: [MOCK_CONSUMABLE_NOTE_RECORD],
+  noteSummaries: [MOCK_NOTE_SUMMARY],
+  consumableNoteSummaries: [MOCK_NOTE_SUMMARY],
+  isLoading: false,
+  error: null,
+  refetch: vi.fn(),
+}));
+
+export const useSyncState = vi.fn(() => ({
+  syncHeight: 12345,
+  isSyncing: false,
+  lastSyncTime: Date.now(),
+  error: null,
+  sync: vi.fn(),
+}));
+
+export const useAssetMetadata = vi.fn(() => ({
+  assetMetadata: new Map([[FAUCET_ID, MOCK_ASSET_METADATA]]),
+}));
+
+export const useTransactionHistory = vi.fn(() => ({
+  records: [],
+  record: null,
+  status: null,
+  isLoading: false,
+  error: null,
+  refetch: vi.fn(),
+}));
+
+export const useNoteStream = vi.fn(() => ({
+  notes: [],
+  latest: null,
+  markHandled: vi.fn(),
+  markAllHandled: vi.fn(),
+  snapshot: vi.fn(() => ({ ids: new Set<string>(), timestamp: Date.now() })),
+  isLoading: false,
+  error: null,
+}));
+
+// ---------------------------------------------------------------------------
+// Mutation hooks
+// ---------------------------------------------------------------------------
+
+// Mutation hooks that resolve to TransactionResult { transactionId } —
+// useMint / useConsume / useSwap / useMultiSend / useTransaction.
+function createMutationMock(mutateKey: string) {
+  return vi.fn(() => ({
+    [mutateKey]: vi.fn(async () => MOCK_TRANSACTION_RESULT),
+    result: null,
+    isLoading: false,
+    stage: "idle" as const,
+    error: null,
+    reset: vi.fn(),
+  }));
+}
+
+// useSend resolves to SendResult { txId, note } — not TransactionResult.
+// Keep this separate so tests that call `send()` get the correct shape.
+function createSendMock() {
+  return vi.fn(() => ({
+    send: vi.fn(async () => MOCK_SEND_RESULT),
+    result: null,
+    isLoading: false,
+    stage: "idle" as const,
+    error: null,
+    reset: vi.fn(),
+  }));
+}
+
+export const useCreateWallet = vi.fn(() => ({
+  createWallet: vi.fn(async () => MOCK_ACCOUNT),
+  wallet: null,
+  isCreating: false,
+  error: null,
+  reset: vi.fn(),
+}));
+
+export const useCreateFaucet = vi.fn(() => ({
+  createFaucet: vi.fn(async () => MOCK_ACCOUNT),
+  faucet: null,
+  isCreating: false,
+  error: null,
+  reset: vi.fn(),
+}));
+
+export const useSend = createSendMock();
+export const useMultiSend = createMutationMock("sendMany");
+export const useMint = createMutationMock("mint");
+export const useConsume = createMutationMock("consume");
+export const useSwap = createMutationMock("swap");
+export const useTransaction = createMutationMock("execute");
+
+export const useImportAccount = vi.fn(() => ({
+  importAccount: vi.fn(async () => MOCK_ACCOUNT),
+  account: null,
+  isImporting: false,
+  error: null,
+  reset: vi.fn(),
+}));
+
+export const useInternalTransfer = vi.fn(() => ({
+  transfer: vi.fn(async () => ({
+    createTransactionId: "0xtx1",
+    consumeTransactionId: "0xtx2",
+    noteId: "0xnote1",
+  })),
+  transferChain: vi.fn(async () => []),
+  result: null,
+  isLoading: false,
+  stage: "idle" as const,
+  error: null,
+  reset: vi.fn(),
+}));
+
+export const useWaitForCommit = vi.fn(() => ({
+  waitForCommit: vi.fn(async () => undefined),
+}));
+
+export const useWaitForNotes = vi.fn(() => ({
+  waitForConsumableNotes: vi.fn(async () => []),
+}));
+
+export const useSessionAccount = vi.fn(() => ({
+  initialize: vi.fn(async () => undefined),
+  sessionAccountId: null,
+  isReady: false,
+  step: "idle" as const,
+  error: null,
+  reset: vi.fn(),
+}));
+
+// ---------------------------------------------------------------------------
+// Provider hooks
+// ---------------------------------------------------------------------------
+
+export const useMiden = vi.fn(() => ({
+  client: null,
+  isReady: true,
+  isInitializing: false,
+  error: null,
+  sync: vi.fn(),
+  runExclusive: vi.fn(async <T>(fn: () => Promise<T>) => fn()),
+  prover: null,
+  signerAccountId: null,
+  signerConnected: null,
+}));
+
+export const useMidenClient = vi.fn(() => ({}));
+
+export const useSigner = vi.fn(() => null);
+
+// ---------------------------------------------------------------------------
+// Components
+// ---------------------------------------------------------------------------
+
+export function MidenProvider({ children }: { children: React.ReactNode }) {
+  return children;
+}
+
+// ---------------------------------------------------------------------------
+// Utility functions
+// ---------------------------------------------------------------------------
+
+export const formatAssetAmount = vi.fn(
+  (amount: bigint, decimals = 8) =>
+    (Number(amount) / 10 ** decimals).toFixed(decimals > 4 ? 4 : decimals),
+);
+
+export const parseAssetAmount = vi.fn(
+  (input: string, decimals = 8) => BigInt(Math.round(parseFloat(input) * 10 ** decimals)),
+);
+
+export const toBech32AccountId = vi.fn((id: string) => id);
+export const normalizeAccountId = vi.fn((id: string) => id);
+export const accountIdsEqual = vi.fn((a: string, b: string) => a === b);
+
+export const getNoteSummary = vi.fn(() => MOCK_NOTE_SUMMARY);
+export const formatNoteSummary = vi.fn(() => "5.0 TEST");
+
+export const readNoteAttachment = vi.fn(() => null);
+export const createNoteAttachment = vi.fn(() => ({}));
+
+export const clearMidenStorage = vi.fn(async () => undefined);
+export const migrateStorage = vi.fn(async () => true);
+export const createMidenStorage = vi.fn(() => ({
+  get: vi.fn(() => null),
+  set: vi.fn(),
+  remove: vi.fn(),
+  clear: vi.fn(),
+}));
+
+export const wrapWasmError = vi.fn((e: unknown) =>
+  e instanceof Error ? e : new Error(String(e)),
+);
+export const waitForWalletDetection = vi.fn(async () => undefined);
+
+export const SignerContext = {
+  Provider: vi.fn(({ children }: { children: React.ReactNode }) => children),
+};
+
+export const bytesToBigInt = vi.fn(() => 0n);
+export const bigIntToBytes = vi.fn(() => new Uint8Array());
+export const concatBytes = vi.fn((...arrays: Uint8Array[]) => {
+  const len = arrays.reduce((acc, a) => acc + a.length, 0);
+  return new Uint8Array(len);
+});

package/template/src/__tests__/patterns/README.md

@@ -0,0 +1,44 @@
+# Test Patterns
+
+Copy-adaptable test patterns for Miden frontend components.
+
+## Available Patterns
+
+### `provider-setup.test.tsx`
+Starting point for any component that uses Miden hooks. Shows mock setup, `vi.mocked()` overrides, and testing ready/loading/error states.
+
+### `query-hook.test.tsx`
+Pattern for components displaying data from query hooks (`useAccounts`, `useNotes`, etc.). Shows loading → data → error → empty state testing.
+
+### `mutation-hook.test.tsx`
+Pattern for components performing transactions (`useSend`, `useMint`, etc.). Shows idle → stage progression → success → error testing, plus argument verification.
+
+## How to Use
+
+1. Copy the closest pattern to your component's `__tests__/` directory
+2. Rename the test file to match your component
+3. Replace the example component with your actual component import
+4. Adapt assertions to your component's specific behavior
+5. Keep the `vi.mock(...)` and `beforeEach(vi.clearAllMocks)` boilerplate
+
+## Mock Setup
+
+All patterns use the shared mock factory:
+
+```tsx
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+```
+
+Override specific hooks per-test:
+
+```tsx
+vi.mocked(useAccounts).mockReturnValue({ wallets: [], ... });
+```
+
+## Fixtures
+
+Realistic test data is in `src/__tests__/fixtures/`. Import what you need:
+
+```tsx
+import { WALLET_ID_1, MOCK_ASSET_BALANCE } from "@/__tests__/fixtures";
+```

package/template/src/__tests__/patterns/mutation-hook.test.tsx

@@ -0,0 +1,146 @@
+/**
+ * TEST PATTERN: Mutation Hook Component
+ *
+ * Shows how to test a component that performs Miden transactions via mutation hooks.
+ * Covers: idle state, transaction stages (executing/proving/submitting), success, and error.
+ *
+ * Key concepts:
+ * - Mock mutation functions to resolve or reject
+ * - Test transaction stage display during multi-step operations
+ * - Test button disable during loading to prevent double-submit
+ * - Test error display and reset
+ */
+
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { vi, describe, it, expect, beforeEach } from "vitest";
+
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+
+import { useSend } from "@miden-sdk/react";
+import { WALLET_ID_1, WALLET_ID_2, FAUCET_ID } from "@/__tests__/fixtures";
+
+// Example component: a send token form — common Miden UI pattern
+function SendTokenForm() {
+  const { send, isLoading, stage, error, reset } = useSend();
+
+  const handleSend = async () => {
+    try {
+      await send({
+        from: WALLET_ID_1,
+        to: WALLET_ID_2,
+        assetId: FAUCET_ID,
+        amount: 100000000n, // 1.0 token
+      });
+    } catch {
+      // Error is captured in the hook's error state
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleSend} disabled={isLoading}>
+        {isLoading ? `${stage}...` : "Send 1.0 TEST"}
+      </button>
+      {stage === "complete" && <p>Transaction submitted!</p>}
+      {error && (
+        <div>
+          <p role="alert">Send failed: {error.message}</p>
+          <button onClick={reset}>Dismiss</button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+describe("Mutation Hook Pattern", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // Default idle state — send button should be enabled
+  it("renders idle state with enabled send button", () => {
+    render(<SendTokenForm />);
+    const button = screen.getByRole("button", { name: "Send 1.0 TEST" });
+    expect(button).toBeEnabled();
+  });
+
+  // Simulate transaction in progress — button disabled, stage shown
+  it("shows transaction stage and disables button during send", () => {
+    vi.mocked(useSend).mockReturnValue({
+      send: vi.fn(),
+      result: null,
+      isLoading: true,
+      stage: "proving" as const,
+      error: null,
+      reset: vi.fn(),
+    });
+
+    render(<SendTokenForm />);
+    const button = screen.getByRole("button", { name: "proving..." });
+    expect(button).toBeDisabled();
+  });
+
+  // Simulate completed transaction — success message shown
+  it("shows success message after transaction completes", () => {
+    vi.mocked(useSend).mockReturnValue({
+      send: vi.fn(),
+      result: { txId: "0xabc123", note: null },
+      isLoading: false,
+      stage: "complete" as const,
+      error: null,
+      reset: vi.fn(),
+    });
+
+    render(<SendTokenForm />);
+    expect(screen.getByText("Transaction submitted!")).toBeInTheDocument();
+  });
+
+  // Simulate error — error message shown with dismiss button
+  it("shows error with dismiss button on failure", async () => {
+    const mockReset = vi.fn();
+    vi.mocked(useSend).mockReturnValue({
+      send: vi.fn().mockRejectedValue(new Error("Insufficient balance")),
+      result: null,
+      isLoading: false,
+      stage: "idle" as const,
+      error: new Error("Insufficient balance"),
+      reset: mockReset,
+    });
+
+    render(<SendTokenForm />);
+
+    // Error should be visible
+    expect(screen.getByRole("alert")).toHaveTextContent("Insufficient balance");
+
+    // Dismiss should call reset
+    const user = userEvent.setup();
+    await user.click(screen.getByRole("button", { name: "Dismiss" }));
+    expect(mockReset).toHaveBeenCalledOnce();
+  });
+
+  // Test the actual send call — verify correct arguments
+  it("calls send with correct arguments on click", async () => {
+    const mockSend = vi.fn(async () => ({ txId: "0xtx", note: null }));
+    vi.mocked(useSend).mockReturnValue({
+      send: mockSend,
+      result: null,
+      isLoading: false,
+      stage: "idle" as const,
+      error: null,
+      reset: vi.fn(),
+    });
+
+    render(<SendTokenForm />);
+
+    const user = userEvent.setup();
+    await user.click(screen.getByRole("button", { name: "Send 1.0 TEST" }));
+
+    expect(mockSend).toHaveBeenCalledWith({
+      from: WALLET_ID_1,
+      to: WALLET_ID_2,
+      assetId: FAUCET_ID,
+      amount: 100000000n,
+    });
+  });
+});

package/template/src/__tests__/patterns/provider-setup.test.tsx

@@ -0,0 +1,77 @@
+/**
+ * TEST PATTERN: Provider Setup
+ *
+ * Shows how to set up the test environment for components that use Miden hooks.
+ * Copy this pattern as a starting point for any Miden component test.
+ *
+ * Key concepts:
+ * - Mock @miden-sdk/react at the module level (hoisted by vitest)
+ * - Override specific hooks per-test with vi.mocked()
+ * - Test ready/loading/error states that every Miden component needs
+ */
+
+import { render, screen } from "@testing-library/react";
+import { vi, describe, it, expect, beforeEach } from "vitest";
+
+// Mock the entire @miden-sdk/react module with realistic defaults
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+
+import { useMiden } from "@miden-sdk/react";
+
+// A minimal component that uses Miden context
+function StatusIndicator() {
+  const { isReady, isInitializing, error } = useMiden();
+
+  if (error) return <div role="alert">Error: {error.message}</div>;
+  if (isInitializing) return <div>Initializing WASM...</div>;
+  if (!isReady) return <div>Not ready</div>;
+  return <div>Miden Ready</div>;
+}
+
+describe("Provider Setup Pattern", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // Default mock returns isReady: true — component should render success state
+  it("renders ready state with default mocks", () => {
+    render(<StatusIndicator />);
+    expect(screen.getByText("Miden Ready")).toBeInTheDocument();
+  });
+
+  // Override useMiden to simulate loading — tests the initializing state
+  it("renders loading state when WASM is initializing", () => {
+    vi.mocked(useMiden).mockReturnValue({
+      client: null,
+      isReady: false,
+      isInitializing: true,
+      error: null,
+      sync: vi.fn(),
+      runExclusive: vi.fn(),
+      prover: null,
+      signerAccountId: null,
+      signerConnected: null,
+    });
+
+    render(<StatusIndicator />);
+    expect(screen.getByText("Initializing WASM...")).toBeInTheDocument();
+  });
+
+  // Override useMiden to simulate error — tests error handling
+  it("renders error state when initialization fails", () => {
+    vi.mocked(useMiden).mockReturnValue({
+      client: null,
+      isReady: false,
+      isInitializing: false,
+      error: new Error("WASM load failed"),
+      sync: vi.fn(),
+      runExclusive: vi.fn(),
+      prover: null,
+      signerAccountId: null,
+      signerConnected: null,
+    });
+
+    render(<StatusIndicator />);
+    expect(screen.getByRole("alert")).toHaveTextContent("WASM load failed");
+  });
+});

package/template/src/__tests__/patterns/query-hook.test.tsx

@@ -0,0 +1,143 @@
+/**
+ * TEST PATTERN: Query Hook Component
+ *
+ * Shows how to test a component that displays data from Miden query hooks.
+ * Covers the three essential states: loading, success (with data), and error.
+ *
+ * Key concepts:
+ * - Override hook return values per-test with vi.mocked()
+ * - Test loading skeleton/placeholder states
+ * - Test data rendering with realistic fixtures
+ * - Test error display and recovery (refetch)
+ */
+
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { vi, describe, it, expect, beforeEach } from "vitest";
+
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+
+import { useAccounts, useSyncState } from "@miden-sdk/react";
+import {
+  MOCK_WALLET_HEADER,
+  MOCK_WALLET_HEADER_2,
+  MOCK_FAUCET_HEADER,
+} from "@/__tests__/fixtures";
+
+// Example component that lists accounts — a common Miden UI pattern
+function AccountList() {
+  const { wallets, faucets, isLoading, error, refetch } = useAccounts();
+  const { syncHeight } = useSyncState();
+
+  if (error) {
+    return (
+      <div>
+        <p role="alert">Failed to load accounts: {error.message}</p>
+        <button onClick={refetch}>Retry</button>
+      </div>
+    );
+  }
+
+  if (isLoading) {
+    return <p>Loading accounts...</p>;
+  }
+
+  return (
+    <div>
+      <p>Synced to block {syncHeight}</p>
+      <h2>Wallets ({wallets.length})</h2>
+      <ul aria-label="wallets">
+        {wallets.map((w) => (
+          <li key={String(w.id)}>{String(w.id)}</li>
+        ))}
+      </ul>
+      <h2>Faucets ({faucets.length})</h2>
+      <ul aria-label="faucets">
+        {faucets.map((f) => (
+          <li key={String(f.id)}>{String(f.id)}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+describe("Query Hook Pattern", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // Default mocks return realistic data — component should render account lists
+  it("renders account lists with data", () => {
+    render(<AccountList />);
+
+    // Wallet list should contain both mock wallets
+    const walletList = screen.getByRole("list", { name: "wallets" });
+    expect(walletList.children).toHaveLength(2);
+    expect(screen.getByText(MOCK_WALLET_HEADER.id)).toBeInTheDocument();
+    expect(screen.getByText(MOCK_WALLET_HEADER_2.id)).toBeInTheDocument();
+
+    // Faucet list should contain the mock faucet
+    const faucetList = screen.getByRole("list", { name: "faucets" });
+    expect(faucetList.children).toHaveLength(1);
+    expect(screen.getByText(MOCK_FAUCET_HEADER.id)).toBeInTheDocument();
+
+    // Sync height from useSyncState mock
+    expect(screen.getByText(/Synced to block 12345/)).toBeInTheDocument();
+  });
+
+  // Override to loading state — component should show loading indicator
+  it("shows loading state while fetching accounts", () => {
+    vi.mocked(useAccounts).mockReturnValue({
+      accounts: [],
+      wallets: [],
+      faucets: [],
+      isLoading: true,
+      error: null,
+      refetch: vi.fn(),
+    });
+
+    render(<AccountList />);
+    expect(screen.getByText("Loading accounts...")).toBeInTheDocument();
+    // Account lists should NOT be rendered during loading
+    expect(screen.queryByRole("list")).not.toBeInTheDocument();
+  });
+
+  // Override to error state — component should show error with retry button
+  it("shows error with retry button on failure", async () => {
+    const mockRefetch = vi.fn();
+    vi.mocked(useAccounts).mockReturnValue({
+      accounts: [],
+      wallets: [],
+      faucets: [],
+      isLoading: false,
+      error: new Error("Network timeout"),
+      refetch: mockRefetch,
+    });
+
+    render(<AccountList />);
+
+    // Error message should be visible and accessible
+    expect(screen.getByRole("alert")).toHaveTextContent("Network timeout");
+
+    // Clicking retry should call refetch
+    const user = userEvent.setup();
+    await user.click(screen.getByRole("button", { name: "Retry" }));
+    expect(mockRefetch).toHaveBeenCalledOnce();
+  });
+
+  // Test empty state — no accounts yet (fresh install)
+  it("renders empty lists when no accounts exist", () => {
+    vi.mocked(useAccounts).mockReturnValue({
+      accounts: [],
+      wallets: [],
+      faucets: [],
+      isLoading: false,
+      error: null,
+      refetch: vi.fn(),
+    });
+
+    render(<AccountList />);
+    expect(screen.getByText("Wallets (0)")).toBeInTheDocument();
+    expect(screen.getByText("Faucets (0)")).toBeInTheDocument();
+  });
+});

package/template/src/{App.css → components/AppContent.css}

@@ -1,10 +1,3 @@
-#root {
-  max-width: 1280px;
-  margin: 0 auto;
-  padding: 2rem;
-  text-align: center;
-}
-
 .logo {
   height: 6em;
   padding: 1.5em;
@@ -36,8 +29,15 @@
   }
 }
 
-.card {
-  padding: 2em;
+.wallet-section {
+  display: flex;
+  justify-content: center;
+  margin-bottom: 1rem;
+}
+
+.loading {
+  padding: 2rem;
+  color: #888;
 }
 
 .read-the-docs {