midnight-cq-dapp-connector-testing

name: midnight-cq:dapp-connector-testing description: >- This skill should be used when the user asks to test DApp Connector API integration, test wallet connection, test makeTransfer, test balanceTransaction, test submitTransaction, mock ConnectedAPI, stub wallet for tests, test wallet errors, test PermissionRejected, test Disconnected handling, test progressive enhancement, write wallet integration tests, test DApp Connector error codes, test wallet discovery, test window.midnight, test apiVersion, test signData, or test DApp Connector security. version: 0.1.0

DApp Connector API Testing

Write tests for DApp code that integrates with the wallet through the DApp Connector API — the window.midnight injection, InitialAPI.connect(), and the ConnectedAPI methods.

When to Use This Skill

Relationship to dapp-testing: This skill covers the API contract between your DApp and the wallet. dapp-testing covers Playwright E2E and UI flows. They complement each other — use both.

What You're Testing

Connection Lifecycle

• Wallet discovery via window.midnight
• apiVersion validation (semver)
• connect(networkId) success and failure
• Disconnection and reconnection

ConnectedAPI Methods

Error Handling

The DApp Connector API defines 5 error codes. Your DApp must handle each correctly:

The critical distinction: Rejected is transient (user said "no" to one transaction), PermissionRejected is permanent (user doesn't want this DApp using that method at all). Your tests must verify your DApp handles both correctly.

Wallet Stub Pattern

Build a configurable test double that implements InitialAPI and ConnectedAPI:

function createWalletStub(config?: Partial<StubConfig>): InitialAPI {
  const cfg = { ...defaultConfig, ...config };

  return Object.freeze({
    rdns: 'com.test.wallet',
    name: cfg.name ?? 'Test Wallet',
    icon: cfg.icon ?? 'data:image/png;base64,...',
    apiVersion: cfg.apiVersion ?? '4.0.1',
    connect: async (networkId) => {
      if (cfg.connectError) throw createAPIError(cfg.connectError);
      return createConnectedStub(cfg);
    },
  });
}

function createConnectedStub(cfg: StubConfig): ConnectedAPI {
  return {
    getShieldedBalances: async () => {
      if (cfg.errors?.getShieldedBalances) throw createAPIError(cfg.errors.getShieldedBalances);
      return cfg.shieldedBalances ?? {};
    },
    getUnshieldedBalances: async () => cfg.unshieldedBalances ?? {},
    getDustBalance: async () => cfg.dustBalance ?? { cap: 0n, balance: 0n },
    // ... all other ConnectedAPI methods
    submitTransaction: async (tx) => {
      if (cfg.errors?.submitTransaction) throw createAPIError(cfg.errors.submitTransaction);
    },
  };
}

See references/connector-stub-patterns.md for complete implementations.

Testing Error Handling

it('should retry after Rejected', async () => {
  let callCount = 0;
  const stub = createWalletStub();
  const wallet = await stub.connect('undeployed');

  // Wrap submitTransaction with a closure so the error
  // is evaluated per-call, not at object creation time
  const originalSubmit = wallet.submitTransaction.bind(wallet);
  wallet.submitTransaction = async (tx) => {
    if (callCount++ === 0) throw createAPIError('Rejected');
    return originalSubmit(tx);
  };

  // First call → Rejected, DApp shows "try again"
  await expect(wallet.submitTransaction('tx')).rejects.toMatchObject({
    code: 'Rejected',
  });
  // Second call → success
  await wallet.submitTransaction('tx');
});

it('should not retry after PermissionRejected', async () => {
  const stub = createWalletStub({
    errors: { getShieldedBalances: 'PermissionRejected' },
  });
  // DApp should hide shielded balance UI, not keep calling
});

it('should attempt reconnection after Disconnected', async () => {
  const stub = createWalletStub({
    connectError: 'Disconnected',
  });
  // DApp should show reconnecting state
});

See references/error-handling-patterns.md for complete patterns.

Progressive Enhancement Testing

Test that your DApp degrades gracefully when the wallet doesn't support certain methods:

it('should work without getProvingProvider', async () => {
  const stub = createWalletStub({
    errors: { getProvingProvider: 'PermissionRejected' },
  });
  // DApp should fall back to client-side proving
});

it('should work without hintUsage', async () => {
  const stub = createWalletStub({
    errors: { hintUsage: 'PermissionRejected' },
  });
  // DApp should still function, just without pre-prompted permissions
});

Security Testing

The DApp Connector spec requires DApps to sanitize wallet-provided data:

it('should sanitize wallet name to prevent XSS', () => {
  const stub = createWalletStub({
    name: '<script>alert("xss")</script>',
  });
  // Render wallet selector UI
  // Assert no script execution, name displayed as text
});

it('should render wallet icon in img tag only', () => {
  const stub = createWalletStub({
    icon: 'data:image/svg+xml,...', // SVG can contain scripts
  });
  // Assert icon is rendered as <img src="...">, not inline SVG
});

Anti-Patterns

Reference Files