Testing

Run check-ins without a real wallet, test against known-good and deliberately broken counterparts, and read what went wrong when a check-in fails.

• In code: mockWallet() from @smart-health-checkin/client/testing.
• In a browser: the connectathon's Testing EHR and SMART Testing Wallet.
• When it fails: every failed result carries a code. See Reading a failed result.

Never offer the mock wallet or the testing tools to patients.

The mock wallet

mockWallet() is a Wallet that answers at once, with no consent screen. It runs the real wire layer: it signs and encrypts a response, and runCheckin opens and validates it like any other.

import { runCheckin } from "@smart-health-checkin/client";
import { mockWallet } from "@smart-health-checkin/client/testing";

const result = await runCheckin(request, { wallet: mockWallet() });

With no options it makes up plausible data for every item. Pin exact answers per item with items:

const wallet = mockWallet({
  items: {
    allergies: { fhir: myAllergyBundle },
    coverage: { status: "declined" },
  },
  fallback: { status: "unavailable" },
});

Per-item answers

Add alsoFulfills: ["otherItem"] to a fhir or healthCard spec when one artifact answers several items. Those items are then reported fulfilled without an artifact of their own.

Other options

Without the wire layer

To test your own code on a response, skip sealing and opening entirely:

In unit tests

runCheckin binds the response to the page's origin, so it needs location. Browsers have it. In Bun or Node, set a stand-in before the first check-in:

(globalThis as { location?: unknown }).location ??= {
  origin: "https://ehr.example",
  href: "https://ehr.example/checkin",
};

Then test outcomes directly:

import { expect, test } from "bun:test";
import { runCheckin } from "@smart-health-checkin/client";
import { mockWallet } from "@smart-health-checkin/client/testing";

test("a declined item is reported, the rest still arrives", async () => {
  const result = await runCheckin(request, {
    wallet: mockWallet({ items: { allergies: { fhir: myAllergyBundle }, coverage: { status: "declined" } } }),
  });
  if (result.status !== "completed") throw new Error(result.status);
  expect(result.response.status("coverage")).toBe("declined");
  expect(result.response.resources("allergies", { type: "AllergyIntolerance" })).toHaveLength(1);
});

To test failures, wrap a transport that throws with customWallet:

import { CheckinError, customWallet } from "@smart-health-checkin/client";

const blocked = customWallet({
  id: "blocked",
  name: "Blocked",
  open: () => ({
    getCredential: async () => {
      throw new CheckinError("blocked", "tab blocked");
    },
    cancel() {},
  }),
});

The mock in a page

Add the mock attribute to the picker. It offers a "Simulated response" option after the real ones.

<smart-checkin-picker registry="/wallets.json" mock></smart-checkin-picker>

Health cards when testing

By default only cards from trusted issuers reach resources(), and test issuers usually aren't trusted. While testing, loosen accept to include cards from any issuer whose signature verifies, or every card, including ones whose signature fails:

import { configureHealthCardTrust } from "@smart-health-checkin/client";

configureHealthCardTrust({ accept: "any-valid" });
configureHealthCardTrust({ accept: "everything" });

To trust one test issuer without fetching its keys, pass them instead: configureHealthCardTrust({ keys: { [issuer]: jwks } }). SMART Health Cards explains each setting and how to see every card's result.

The connectathon tools

Two hosted tools let you test against a known-good counterpart.

Testing EHR

https://smart-health-checkin.org/connectathon/testing-ehr/

• Sends a connectathon scenario, a request you build from items, or one you paste.
• Sends it to a registry wallet, this device's own wallet, or any web wallet by URL, so you can test before you're registered.
• Shows the verdict first, then each failing check with what to fix, then what came back: readable, as JSON, and the wire layers.
• Downloads the whole run, keeps recent runs in the browser, and opens a prefilled issue for a result.

SMART Testing Wallet

https://smart-health-checkin.org/connectathon/testing-wallet/

A web wallet with synthetic patients. It can send a deliberately broken or very large response, so you can check your page's error handling.

To test your own page: open the wallet, set faults or a response size in its testing panel, choose "Copy wallet URL for these settings", and add that URL to your page's wallet list as a web wallet, for example with webWallet(). Then run check-ins from your page as usual; each one gets those options, and the wallet's approval screen shows them. For example, bad signature and 5 MB response. These config URLs are the Testing Wallet's own format, not part of SMART Health Check-in: your page opens them like any wallet URL. The Testing EHR can build them too, under "Testing Wallet options".

What this library does with each, and what your page should do (spec §6.4 and §8.5):

• combine-allergies-meds: accept the response intact.
• bad-shc-signature: accept the response. The card arrives with valid: false and is left out of resources().
• bad-signature: complete the check-in with a device-signature or issuer-signature warning in result.warnings.
• wrong-canonical and unaccepted-media-type: complete it with that record set aside; response.disregarded() says why.
• missing-status and duplicate-status: complete it; that item has no status (response.status(id) is undefined).
• wrong-request-id, bad-encryption, and wrong-origin: fail with invalid-response.

The wallet's response size setting makes a valid response of about 512 KB, 1 MB, 2 MB, or 5 MB, by adding earlier records such as past lab results to one item's Bundle. Use it to check that your page handles a large response the way it handles a small one.

Reading a failed result

A failed result has error.code, error.message, and sometimes error.check.

if (result.status === "failed") console.log(result.error.code, result.error.check, result.error.message);

A declined check-in is not a failure: result.status is "declined", with no error.

The demos

Each demo page runs the real flow and shows one way to use the library. Source is in demo/src/.

The clinic check-in demo takes options in the URL fragment, such as #wallet=mock to offer only the simulated response or #wallet=platform to offer only the device's own wallet. Clinic check-in demo options lists them.