create-miden-app 1.0.3 → 1.0.6

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

@@ -0,0 +1,75 @@
+/**
+ * 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,
+    });
+
+    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,
+    });
+
+    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/components/AppContent.css

@@ -0,0 +1,45 @@
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+.logo.miden:hover {
+  filter: drop-shadow(0 0 2em #ff5500);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.wallet-section {
+  display: flex;
+  justify-content: center;
+  margin-bottom: 1rem;
+}
+
+.loading {
+  padding: 2rem;
+  color: #888;
+}
+
+.read-the-docs {
+  color: #888;
+}

package/template/src/components/AppContent.tsx

@@ -0,0 +1,50 @@
+import { useMiden, useSyncState } from "@miden-sdk/react";
+import { WalletMultiButton } from "@miden-sdk/miden-wallet-adapter";
+import reactLogo from "@/assets/react.svg";
+import midenLogo from "@/assets/miden.svg";
+import viteLogo from "/vite.svg";
+import { Counter } from "@/components/Counter";
+import "./AppContent.css";
+
+export function AppContent() {
+  const { isReady, isInitializing, error } = useMiden();
+  const { syncHeight } = useSyncState();
+
+  if (error) {
+    return (
+      <div className="loading">
+        <p>Failed to initialize Miden client</p>
+        <p className="error">{error.message}</p>
+      </div>
+    );
+  }
+
+  if (isInitializing || !isReady) {
+    return <div className="loading">Initializing Miden client...</div>;
+  }
+
+  return (
+    <>
+      <div>
+        <a href="https://vite.dev" target="_blank" rel="noreferrer">
+          <img src={viteLogo} className="logo" alt="Vite logo" />
+        </a>
+        <a href="https://react.dev" target="_blank" rel="noreferrer">
+          <img src={reactLogo} className="logo react" alt="React logo" />
+        </a>
+        <a href="https://docs.miden.io" target="_blank" rel="noreferrer">
+          <img src={midenLogo} className="logo miden" alt="Miden logo" />
+        </a>
+      </div>
+      <h1>Vite + React + Miden</h1>
+      <div className="wallet-section">
+        <WalletMultiButton />
+      </div>
+      <Counter />
+      <p className="read-the-docs">
+        Testnet block: {syncHeight ?? "syncing..."} | Click on the Vite, React,
+        and Miden logos to learn more
+      </p>
+    </>
+  );
+}

package/template/src/components/Counter.css

@@ -0,0 +1,27 @@
+.card {
+  padding: 2em;
+}
+
+.counter-button {
+  font-size: 1.2em;
+  padding: 0.8em 1.6em;
+}
+
+.account-id {
+  font-size: 0.8em;
+  color: #888;
+  font-family: monospace;
+  margin-top: 0.5rem;
+  text-decoration: none;
+}
+
+.account-id:hover {
+  text-decoration: underline;
+}
+
+.error {
+  color: #ff4444;
+  font-size: 0.9em;
+  margin-top: 0.5rem;
+  word-break: break-word;
+}

package/template/src/components/Counter.tsx

@@ -0,0 +1,45 @@
+import { useIncrementCounter } from "@/hooks/useIncrementCounter";
+import { COUNTER_ADDRESS } from "@/config";
+import "./Counter.css";
+
+export function Counter() {
+  const {
+    increment,
+    count,
+    isSubmitting,
+    isWaiting,
+    error,
+    walletConnected,
+    explorerUrl,
+  } = useIncrementCounter(COUNTER_ADDRESS);
+
+  const busy = isSubmitting || isWaiting;
+  const buttonLabel = isSubmitting
+    ? "Submitting..."
+    : isWaiting
+      ? "Waiting for network..."
+      : `count is ${count ?? "..."}`;
+
+  return (
+    <div className="card">
+      <button
+        className="counter-button"
+        onClick={increment}
+        disabled={busy || count === null || !walletConnected}
+      >
+        {buttonLabel}
+      </button>
+      <p>
+        <a
+          href={explorerUrl}
+          target="_blank"
+          rel="noreferrer"
+          className="account-id"
+        >
+          Counter: {COUNTER_ADDRESS}
+        </a>
+      </p>
+      {error && <p className="error">{error}</p>}
+    </div>
+  );
+}

package/template/src/components/__tests__/AppContent.test.tsx

@@ -0,0 +1,86 @@
+import { render, screen } from "@testing-library/react";
+import { vi, describe, it, expect, beforeEach } from "vitest";
+
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+vi.mock("@miden-sdk/miden-wallet-adapter", () => ({
+  WalletMultiButton: () => <button>Connect Wallet</button>,
+}));
+vi.mock("@/components/Counter", () => ({
+  Counter: () => <div data-testid="counter">Counter Mock</div>,
+}));
+
+import { useMiden, useSyncState } from "@miden-sdk/react";
+import { AppContent } from "../AppContent";
+
+describe("AppContent", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("renders main content when Miden is ready", () => {
+    render(<AppContent />);
+
+    expect(screen.getByText("Vite + React + Miden")).toBeInTheDocument();
+    expect(screen.getByAltText("Vite logo")).toBeInTheDocument();
+    expect(screen.getByAltText("React logo")).toBeInTheDocument();
+    expect(screen.getByAltText("Miden logo")).toBeInTheDocument();
+    expect(screen.getByText("Connect Wallet")).toBeInTheDocument();
+    expect(screen.getByTestId("counter")).toBeInTheDocument();
+  });
+
+  it("shows sync height from testnet", () => {
+    render(<AppContent />);
+    expect(screen.getByText(/Testnet block: 12345/)).toBeInTheDocument();
+  });
+
+  it("shows syncing indicator when syncHeight is null", () => {
+    vi.mocked(useSyncState).mockReturnValue({
+      syncHeight: null as unknown as number,
+      isSyncing: true,
+      lastSyncTime: null,
+      error: null,
+      sync: vi.fn(),
+    });
+
+    render(<AppContent />);
+    expect(screen.getByText(/syncing\.\.\./)).toBeInTheDocument();
+  });
+
+  it("shows loading message during initialization", () => {
+    vi.mocked(useMiden).mockReturnValue({
+      client: null,
+      isReady: false,
+      isInitializing: true,
+      error: null,
+      sync: vi.fn(),
+      runExclusive: vi.fn(),
+      prover: null,
+      signerAccountId: null,
+    });
+
+    render(<AppContent />);
+    expect(
+      screen.getByText("Initializing Miden client..."),
+    ).toBeInTheDocument();
+    expect(screen.queryByText("Vite + React + Miden")).not.toBeInTheDocument();
+  });
+
+  it("shows error message on initialization failure", () => {
+    vi.mocked(useMiden).mockReturnValue({
+      client: null,
+      isReady: false,
+      isInitializing: false,
+      error: new Error("WASM failed to load"),
+      sync: vi.fn(),
+      runExclusive: vi.fn(),
+      prover: null,
+      signerAccountId: null,
+    });
+
+    render(<AppContent />);
+    expect(
+      screen.getByText("Failed to initialize Miden client"),
+    ).toBeInTheDocument();
+    expect(screen.getByText("WASM failed to load")).toBeInTheDocument();
+  });
+});

package/template/src/components/__tests__/Counter.test.tsx

@@ -0,0 +1,114 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { vi, describe, it, expect, beforeEach } from "vitest";
+
+vi.mock("@/hooks/useIncrementCounter", () => ({
+  useIncrementCounter: vi.fn(),
+}));
+
+import { useIncrementCounter } from "@/hooks/useIncrementCounter";
+import { Counter } from "../Counter";
+
+const defaultHookReturn = {
+  increment: vi.fn(),
+  count: 42,
+  isSubmitting: false,
+  isWaiting: false,
+  error: null,
+  walletConnected: true,
+  explorerUrl: "https://testnet.midenscan.com/account/mtst1test",
+};
+
+describe("Counter", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(useIncrementCounter).mockReturnValue(defaultHookReturn);
+  });
+
+  it("displays the current count on the button", () => {
+    render(<Counter />);
+    expect(
+      screen.getByRole("button", { name: "count is 42" }),
+    ).toBeInTheDocument();
+  });
+
+  it("calls increment on button click", async () => {
+    const mockIncrement = vi.fn();
+    vi.mocked(useIncrementCounter).mockReturnValue({
+      ...defaultHookReturn,
+      increment: mockIncrement,
+    });
+
+    render(<Counter />);
+    const user = userEvent.setup();
+    await user.click(screen.getByRole("button", { name: "count is 42" }));
+    expect(mockIncrement).toHaveBeenCalledOnce();
+  });
+
+  it("shows submitting state", () => {
+    vi.mocked(useIncrementCounter).mockReturnValue({
+      ...defaultHookReturn,
+      isSubmitting: true,
+    });
+
+    render(<Counter />);
+    const button = screen.getByRole("button", { name: "Submitting..." });
+    expect(button).toBeDisabled();
+  });
+
+  it("shows waiting for network state", () => {
+    vi.mocked(useIncrementCounter).mockReturnValue({
+      ...defaultHookReturn,
+      isWaiting: true,
+    });
+
+    render(<Counter />);
+    const button = screen.getByRole("button", {
+      name: "Waiting for network...",
+    });
+    expect(button).toBeDisabled();
+  });
+
+  it("disables button when wallet not connected", () => {
+    vi.mocked(useIncrementCounter).mockReturnValue({
+      ...defaultHookReturn,
+      walletConnected: false,
+    });
+
+    render(<Counter />);
+    expect(screen.getByRole("button")).toBeDisabled();
+  });
+
+  it("disables button when count is loading (null)", () => {
+    vi.mocked(useIncrementCounter).mockReturnValue({
+      ...defaultHookReturn,
+      count: null,
+    });
+
+    render(<Counter />);
+    const button = screen.getByRole("button", { name: "count is ..." });
+    expect(button).toBeDisabled();
+  });
+
+  it("displays error message", () => {
+    vi.mocked(useIncrementCounter).mockReturnValue({
+      ...defaultHookReturn,
+      error: "Transaction failed: insufficient funds",
+    });
+
+    render(<Counter />);
+    expect(
+      screen.getByText("Transaction failed: insufficient funds"),
+    ).toBeInTheDocument();
+  });
+
+  it("links to explorer with counter address", () => {
+    render(<Counter />);
+    const link = screen.getByRole("link");
+    expect(link).toHaveAttribute(
+      "href",
+      "https://testnet.midenscan.com/account/mtst1test",
+    );
+    expect(link).toHaveAttribute("target", "_blank");
+  });
+});

package/template/src/config.ts

@@ -0,0 +1,21 @@
+// Network counter account deployed on Miden testnet
+export const COUNTER_ADDRESS = "mtst1aru8adnrqspgcsr3drk2n990lyc070ll";
+
+// StorageMap slot name for the counter
+export const COUNTER_SLOT_NAME =
+  "miden::component::miden_counter_account::count_map";
+
+// Block explorer base URL
+export const EXPLORER_BASE_URL = "https://testnet.midenscan.com";
+
+// Delay (ms) to wait for the network to process a note before re-syncing
+export const NETWORK_SYNC_DELAY_MS = 10_000;
+
+// Application display name (used by wallet adapter)
+export const APP_NAME = "Miden Template";
+
+// Miden SDK configuration — override via environment variables
+export const MIDEN_RPC_URL =
+  import.meta.env.VITE_MIDEN_RPC_URL ?? "testnet";
+export const MIDEN_PROVER =
+  (import.meta.env.VITE_MIDEN_PROVER as "testnet" | "local") ?? "testnet";