@pih/esm-audit-app 2.1.0

package/src/audit/patient-activity.ts

@@ -0,0 +1,156 @@
+import { type AuditEncounter, type AuditObs, type OpenmrsResourceRef } from '../types';
+
+/** What someone did to a patient's record. */
+export type AuditAction =
+  | 'encounterCreated'
+  | 'encounterChanged'
+  | 'encounterDeleted'
+  | 'obsRecorded'
+  | 'obsEdited'
+  | 'obsDeleted';
+
+export interface AuditEvent {
+  /** Stable across renders: the row it came from plus what happened to it. */
+  key: string;
+  action: AuditAction;
+  /** When it happened, as the REST API reported it. */
+  timestamp: string;
+  user: OpenmrsResourceRef | undefined;
+  encounter: AuditEncounter;
+  /** The concept whose value was touched, for the observation actions. */
+  concept?: string;
+}
+
+/** One user's footprint on the part of the record that was read. */
+export interface UserActivity {
+  userUuid: string;
+  userDisplay: string;
+  counts: Record<AuditAction, number>;
+  firstActivity: string;
+  lastActivity: string;
+  totalEvents: number;
+}
+
+/** The obs of one encounter, keyed by the encounter's uuid. */
+export type ObsByEncounter = Record<string, Array<AuditObs>>;
+
+/** Stands in for the user on events whose actor the API did not report. */
+export const unknownUserUuid = 'unknown';
+
+/**
+ * The key an event is grouped and filtered by. `summariseByUser` and the activity log both use it,
+ * so a row's counts and the events behind it can never disagree about who did what.
+ */
+export function eventUserUuid(auditEvent: AuditEvent): string {
+  return auditEvent.user?.uuid ?? unknownUserUuid;
+}
+
+function event(
+  action: AuditAction,
+  timestamp: string | undefined,
+  user: OpenmrsResourceRef | undefined,
+  encounter: AuditEncounter,
+  keySuffix: string,
+  concept?: string,
+): AuditEvent | null {
+  return timestamp ? { key: `${keySuffix}:${action}`, action, timestamp, user, encounter, concept } : null;
+}
+
+/**
+ * Turns encounters and their observations into the list of things people did to the record.
+ *
+ * Every obs row was created by someone at some point, so each yields one creation event — an edit
+ * if it replaced an earlier obs, a plain recording otherwise. A voided obs yields a deletion event
+ * too, unless a later obs replaced it: that voiding is the other half of the successor's edit, and
+ * counting it again would make one correction look like two acts.
+ */
+export function buildAuditEvents(encounters: Array<AuditEncounter>, obsByEncounter: ObsByEncounter): Array<AuditEvent> {
+  const events: Array<AuditEvent> = [];
+
+  for (const encounter of encounters) {
+    const audit = encounter.auditInfo;
+    events.push(
+      event('encounterCreated', audit?.dateCreated, audit?.creator, encounter, encounter.uuid),
+      event('encounterChanged', audit?.dateChanged, audit?.changedBy, encounter, encounter.uuid),
+      encounter.voided
+        ? event('encounterDeleted', audit?.dateVoided, audit?.voidedBy, encounter, encounter.uuid)
+        : null,
+    );
+
+    const obsList = obsByEncounter[encounter.uuid] ?? [];
+    const supersededUuids = new Set(
+      obsList.map((obs) => obs.previousVersion?.uuid).filter((uuid): uuid is string => Boolean(uuid)),
+    );
+
+    for (const obs of obsList) {
+      const obsAudit = obs.auditInfo;
+      const concept = obs.concept?.display;
+      events.push(
+        event(
+          obs.previousVersion ? 'obsEdited' : 'obsRecorded',
+          obsAudit?.dateCreated,
+          obsAudit?.creator,
+          encounter,
+          obs.uuid,
+          concept,
+        ),
+        obs.voided && !supersededUuids.has(obs.uuid)
+          ? event('obsDeleted', obsAudit?.dateVoided, obsAudit?.voidedBy, encounter, obs.uuid, concept)
+          : null,
+      );
+    }
+  }
+
+  return events
+    .filter((auditEvent): auditEvent is AuditEvent => auditEvent !== null)
+    .sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+
+function emptyCounts(): Record<AuditAction, number> {
+  return {
+    encounterCreated: 0,
+    encounterChanged: 0,
+    encounterDeleted: 0,
+    obsRecorded: 0,
+    obsEdited: 0,
+    obsDeleted: 0,
+  };
+}
+
+/**
+ * Who touched the record, and how much: one row per user, busiest first. Events whose user the
+ * API did not report are gathered under a single unknown user rather than dropped, so the counts
+ * still add up to what was read.
+ */
+export function summariseByUser(events: Array<AuditEvent>): Array<UserActivity> {
+  const byUser = new Map<string, UserActivity>();
+
+  for (const auditEvent of events) {
+    const userUuid = eventUserUuid(auditEvent);
+    let activity = byUser.get(userUuid);
+    if (!activity) {
+      activity = {
+        userUuid,
+        userDisplay: auditEvent.user?.display ?? '',
+        counts: emptyCounts(),
+        firstActivity: auditEvent.timestamp,
+        lastActivity: auditEvent.timestamp,
+        totalEvents: 0,
+      };
+      byUser.set(userUuid, activity);
+    }
+
+    activity.counts[auditEvent.action] += 1;
+    activity.totalEvents += 1;
+    if (auditEvent.timestamp < activity.firstActivity) {
+      activity.firstActivity = auditEvent.timestamp;
+    }
+    if (auditEvent.timestamp > activity.lastActivity) {
+      activity.lastActivity = auditEvent.timestamp;
+    }
+  }
+
+  return Array.from(byUser.values()).sort(
+    (a, b) => b.totalEvents - a.totalEvents || a.userDisplay.localeCompare(b.userDisplay),
+  );
+}

package/src/audit/patient-encounters.component.tsx

@@ -0,0 +1,134 @@
+import React, { useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import {
+  DataTableSkeleton,
+  Pagination,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tag,
+} from '@carbon/react';
+import { ErrorState, useConfig } from '@openmrs/esm-framework';
+import { type Config } from '../config-schema';
+import { type AuditEncounter, type AuditPatient } from '../types';
+import { formatAuditDatetime } from './audit-format';
+import { usePatientEncounters } from './audit.resource';
+import { type EncounterFilters, hasActiveFilters } from './encounter-filters';
+import styles from './audit.scss';
+
+interface PatientEncountersProps {
+  patient: AuditPatient | undefined;
+  includeDeleted: boolean;
+  filters: EncounterFilters;
+  isLoadingPatient: boolean;
+  onSelectEncounter(encounterUuid: string): void;
+}
+
+function providerNames(encounter: AuditEncounter): string {
+  return (encounter.encounterProviders ?? [])
+    .filter((encounterProvider) => !encounterProvider.voided)
+    .map((encounterProvider) => encounterProvider.provider?.display)
+    .filter(Boolean)
+    .join(', ');
+}
+
+/**
+ * Every encounter recorded for the patient, most recent first, as the way into one encounter's
+ * audit trail. Deleted encounters are hidden by default, as they were on the legacy admin page.
+ */
+export default function PatientEncounters({
+  patient,
+  includeDeleted,
+  filters,
+  isLoadingPatient,
+  onSelectEncounter,
+}: PatientEncountersProps) {
+  const { t } = useTranslation();
+  const config = useConfig<Config>();
+  const [pageSize, setPageSize] = useState(config.encountersPageSize ?? 10);
+  const pageSizes = useMemo(() => Array.from(new Set([pageSize, 10, 20, 50])).sort((a, b) => a - b), [pageSize]);
+
+  const { encounters, totalCount, currentPage, goTo, error, isLoading } = usePatientEncounters(
+    patient,
+    includeDeleted,
+    filters,
+    pageSize,
+  );
+
+  if (error) {
+    return <ErrorState error={error} headerTitle={t('encounters', 'Encounters')} />;
+  }
+
+  if (isLoadingPatient || isLoading) {
+    return <DataTableSkeleton columnCount={6} compact role="progressbar" showHeader={false} showToolbar={false} />;
+  }
+
+  if (encounters.length === 0) {
+    return (
+      <p className={styles.emptyState}>
+        {hasActiveFilters(filters)
+          ? t('noEncountersMatchFilters', 'No encounters match these filters.')
+          : t('noEncountersFound', 'This patient has no encounters to audit.')}
+      </p>
+    );
+  }
+
+  return (
+    <>
+      <TableContainer className={styles.tableContainer}>
+        <Table size="sm" useZebraStyles>
+          <TableHead>
+            <TableRow>
+              <TableHeader>{t('encounterDate', 'Encounter date')}</TableHeader>
+              <TableHeader>{t('encounterType', 'Encounter type')}</TableHeader>
+              <TableHeader>{t('form', 'Form')}</TableHeader>
+              <TableHeader>{t('provider', 'Provider')}</TableHeader>
+              <TableHeader>{t('location', 'Location')}</TableHeader>
+              <TableHeader>{t('status', 'Status')}</TableHeader>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {encounters.map((encounter) => (
+              <TableRow
+                className={styles.clickableRow}
+                key={encounter.uuid}
+                onClick={() => onSelectEncounter(encounter.uuid)}>
+                <TableCell>
+                  <button
+                    className={styles.linkButton}
+                    onClick={(event) => {
+                      event.stopPropagation();
+                      onSelectEncounter(encounter.uuid);
+                    }}
+                    type="button">
+                    {formatAuditDatetime(encounter.encounterDatetime)}
+                  </button>
+                </TableCell>
+                <TableCell>{encounter.encounterType?.display}</TableCell>
+                <TableCell>{encounter.form?.display}</TableCell>
+                <TableCell>{providerNames(encounter)}</TableCell>
+                <TableCell>{encounter.location?.display}</TableCell>
+                <TableCell>{encounter.voided ? <Tag type="red">{t('deleted', 'Deleted')}</Tag> : null}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </TableContainer>
+      <Pagination
+        onChange={({ page: nextPage, pageSize: nextPageSize }) => {
+          setPageSize(nextPageSize);
+          goTo(nextPage);
+        }}
+        page={currentPage}
+        pageSize={pageSize}
+        pageSizes={pageSizes}
+        size="sm"
+        totalItems={totalCount}
+      />
+    </>
+  );
+}

package/src/audit/patient-record.component.test.tsx

@@ -0,0 +1,193 @@
+import React from 'react';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { SWRConfig } from 'swr';
+import { openmrsFetch, useConfig } from '@openmrs/esm-framework';
+import { type AuditEncounter, type AuditPatient } from '../types';
+import PatientRecord from './patient-record.component';
+
+const mockOpenmrsFetch = jest.mocked(openmrsFetch);
+const mockUseConfig = jest.mocked(useConfig);
+
+const mockPatient: AuditPatient = {
+  uuid: 'patient-1',
+  display: 'Y2AHXV - Dave TestPatient',
+  identifiers: [{ uuid: 'id-1', identifier: 'Y2AHXV', preferred: true }],
+  person: { display: 'Dave TestPatient', gender: 'M', age: 42, birthdate: '1984-03-14T00:00:00.000+0000' },
+};
+
+const consultation: AuditEncounter = {
+  uuid: 'enc-1',
+  encounterDatetime: '2026-04-18T09:00:00.000+0000',
+  voided: false,
+  encounterType: { uuid: 'type-1', display: 'Oncology Consultation' },
+  form: { uuid: 'form-1', display: 'Oncology Consult Note' },
+  location: { uuid: 'loc-1', display: 'Klinik Ekstèn' },
+  encounterProviders: [{ uuid: 'ep-1', provider: { uuid: 'prov-1', display: 'Louidor Jean paul' } }],
+};
+
+const deletedCheckin: AuditEncounter = {
+  uuid: 'enc-2',
+  encounterDatetime: '2026-04-11T08:00:00.000+0000',
+  voided: true,
+  encounterType: { uuid: 'type-2', display: 'Inscription' },
+  form: { uuid: 'form-2', display: 'LiveCheckin' },
+  location: { uuid: 'loc-2', display: 'CDI Klinik Ekstèn Jeneral' },
+  patient: { uuid: 'patient-1', display: 'Y2AHXV - Dave TestPatient' },
+};
+
+/** The free-text encounter search matches on identifier, so it can return other patients' rows. */
+const otherPatientsEncounter: AuditEncounter = {
+  uuid: 'enc-3',
+  encounterDatetime: '2026-05-01T08:00:00.000+0000',
+  voided: false,
+  encounterType: { uuid: 'type-3', display: 'Consultation' },
+  patient: { uuid: 'patient-2', display: 'Y2AHXV2 - Someone Else' },
+};
+
+/**
+ * The encounter list is the only read that asks for a total count; the unfiltered scan behind the
+ * encounter-type dropdown and the activity view reads the same endpoint without one.
+ */
+function mockRestApi({ pagedEncounters = [consultation] }: { pagedEncounters?: Array<AuditEncounter> } = {}) {
+  mockOpenmrsFetch.mockImplementation((url: string) => {
+    if (url.includes('/patient/patient-1')) {
+      return Promise.resolve({ data: mockPatient }) as ReturnType<typeof openmrsFetch>;
+    }
+    if (url.includes('/obs?encounter=')) {
+      return Promise.resolve({ data: { results: [] } }) as ReturnType<typeof openmrsFetch>;
+    }
+    if (url.includes('/encounter?q=')) {
+      return Promise.resolve({
+        data: {
+          results: [{ ...consultation, patient: deletedCheckin.patient }, deletedCheckin, otherPatientsEncounter],
+        },
+      }) as ReturnType<typeof openmrsFetch>;
+    }
+    if (url.includes('totalCount=true')) {
+      return Promise.resolve({
+        data: { results: pagedEncounters, totalCount: pagedEncounters.length },
+      }) as ReturnType<typeof openmrsFetch>;
+    }
+    return Promise.resolve({ data: { results: [consultation, deletedCheckin] } }) as ReturnType<typeof openmrsFetch>;
+  });
+}
+
+function renderPatientRecord() {
+  const onSelectEncounter = jest.fn();
+  const onBackToSearch = jest.fn();
+  const onSelectView = jest.fn();
+  render(
+    <SWRConfig value={{ dedupingInterval: 0, provider: () => new Map() }}>
+      <PatientRecord
+        onBackToSearch={onBackToSearch}
+        onSelectEncounter={onSelectEncounter}
+        onSelectView={onSelectView}
+        patientUuid="patient-1"
+        view="encounters"
+      />
+    </SWRConfig>,
+  );
+  return { onSelectEncounter, onBackToSearch, onSelectView };
+}
+
+describe('<PatientRecord />', () => {
+  beforeEach(() => {
+    mockUseConfig.mockReturnValue({
+      patientChartUrl: '${openmrsSpaBase}/patient/${patientUuid}/chart',
+    });
+    mockRestApi();
+  });
+
+  it("lists the patient's encounters, without the deleted ones", async () => {
+    renderPatientRecord();
+
+    expect(await screen.findByText('Dave TestPatient')).toBeInTheDocument();
+    expect(screen.getByRole('cell', { name: 'Oncology Consultation' })).toBeInTheDocument();
+    expect(screen.getByRole('cell', { name: 'Louidor Jean paul' })).toBeInTheDocument();
+    expect(screen.queryByText('LiveCheckin')).not.toBeInTheDocument();
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(expect.stringContaining('/ws/rest/v1/encounter?patient=patient-1'));
+  });
+
+  it('includes deleted encounters on request, and only this patient’s', async () => {
+    renderPatientRecord();
+    await screen.findByRole('cell', { name: 'Oncology Consultation' });
+
+    await userEvent.click(screen.getByRole('checkbox', { name: /include deleted encounters/i }));
+
+    expect(await screen.findByRole('cell', { name: 'LiveCheckin' })).toBeInTheDocument();
+    expect(screen.queryByRole('cell', { name: 'Consultation' })).not.toBeInTheDocument();
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(
+      expect.stringContaining('/ws/rest/v1/encounter?q=Y2AHXV&includeAll=true'),
+    );
+
+    const deletedRow = screen.getAllByRole('row').find((row) => row.textContent?.includes('LiveCheckin'));
+    expect(deletedRow).toHaveTextContent('Deleted');
+  });
+
+  it('drills down into the encounter that is clicked', async () => {
+    const { onSelectEncounter } = renderPatientRecord();
+    await screen.findByRole('cell', { name: 'Oncology Consultation' });
+
+    await userEvent.click(screen.getAllByRole('button', { name: /2026/ })[0]);
+
+    expect(onSelectEncounter).toHaveBeenCalledWith('enc-1');
+  });
+
+  it("offers only the encounter types this patient's encounters use", async () => {
+    renderPatientRecord();
+    await screen.findByRole('cell', { name: 'Oncology Consultation' });
+
+    await userEvent.click(screen.getByRole('combobox', { name: /encounter type/i }));
+
+    const options = within(screen.getByRole('listbox')).getAllByRole('option');
+    expect(options.map((option) => option.textContent)).toEqual(['Inscription', 'Oncology Consultation']);
+  });
+
+  it('asks the server for one encounter type when one is chosen', async () => {
+    renderPatientRecord();
+    await screen.findByRole('cell', { name: 'Oncology Consultation' });
+
+    await userEvent.click(screen.getByRole('combobox', { name: /encounter type/i }));
+    await userEvent.click(await screen.findByRole('option', { name: 'Inscription' }));
+
+    await waitFor(() =>
+      expect(mockOpenmrsFetch).toHaveBeenCalledWith(expect.stringContaining('&encounterType=type-2')),
+    );
+  });
+
+  it('offers to clear the filters once one is set, and says when nothing matches', async () => {
+    renderPatientRecord();
+    await screen.findByRole('cell', { name: 'Oncology Consultation' });
+    expect(screen.queryByRole('button', { name: /clear filters/i })).not.toBeInTheDocument();
+
+    mockRestApi({ pagedEncounters: [] });
+
+    await userEvent.click(screen.getByRole('combobox', { name: /encounter type/i }));
+    await userEvent.click(await screen.findByRole('option', { name: 'Inscription' }));
+
+    expect(await screen.findByText(/no encounters match these filters/i)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /clear filters/i })).toBeInTheDocument();
+
+    await userEvent.click(screen.getByRole('button', { name: /clear filters/i }));
+
+    expect(screen.queryByRole('button', { name: /clear filters/i })).not.toBeInTheDocument();
+  });
+
+  it('goes back to the patient search', async () => {
+    const { onBackToSearch } = renderPatientRecord();
+
+    await userEvent.click(screen.getByRole('button', { name: /back to patient search/i }));
+
+    expect(onBackToSearch).toHaveBeenCalled();
+  });
+
+  it('switches to the record activity view', async () => {
+    const { onSelectView } = renderPatientRecord();
+    await screen.findByRole('cell', { name: 'Oncology Consultation' });
+
+    await userEvent.click(screen.getByRole('tab', { name: /patient activity/i }));
+
+    expect(onSelectView).toHaveBeenCalledWith('activity');
+  });
+});

package/src/audit/patient-record.component.tsx

@@ -0,0 +1,115 @@
+import React, { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Button, Checkbox, InlineNotification, Tab, TabList, TabPanel, TabPanels, Tabs } from '@carbon/react';
+import { ArrowLeftIcon, ErrorState } from '@openmrs/esm-framework';
+import { canListDeletedEncounters, getPreferredIdentifier, useAuditPatient } from './audit.resource';
+import { type EncounterFilters } from './encounter-filters';
+import EncounterFiltersBar from './encounter-filters.component';
+import PatientActivity from './patient-activity.component';
+import PatientEncounters from './patient-encounters.component';
+import styles from './audit.scss';
+
+export type PatientRecordView = 'encounters' | 'activity';
+
+export const patientRecordViews: Array<PatientRecordView> = ['encounters', 'activity'];
+
+interface PatientRecordProps {
+  patientUuid: string;
+  view: PatientRecordView;
+  onSelectView(view: PatientRecordView): void;
+  onSelectEncounter(encounterUuid: string): void;
+  onBackToSearch(): void;
+}
+
+/**
+ * Step two of the audit trail. The patient's record can be read two ways — as the list of
+ * encounters to drill into, or as the record of who has touched it — and both are narrowed by the
+ * same filters, which is why they share this component's state rather than holding their own.
+ */
+export default function PatientRecord({
+  patientUuid,
+  view,
+  onSelectView,
+  onSelectEncounter,
+  onBackToSearch,
+}: PatientRecordProps) {
+  const { t } = useTranslation();
+  const [includeDeleted, setIncludeDeleted] = useState(false);
+  const [filters, setFilters] = useState<EncounterFilters>({});
+
+  const { patient, error: patientError, isLoading: isLoadingPatient } = useAuditPatient(patientUuid);
+  const cannotIncludeDeleted = includeDeleted && Boolean(patient) && !canListDeletedEncounters(patient);
+
+  return (
+    <div className={styles.section}>
+      <Button className={styles.backButton} kind="ghost" onClick={onBackToSearch} renderIcon={ArrowLeftIcon} size="sm">
+        {t('backToPatientSearch', 'Back to patient search')}
+      </Button>
+      <div className={styles.contextHeader}>
+        <span className={styles.contextTitle}>{patient?.person?.display ?? patient?.display ?? ''}</span>
+        <span className={styles.contextSubtitle}>
+          {[getPreferredIdentifier(patient), patient?.person?.gender, patient?.person?.age]
+            .filter((part) => part !== undefined && part !== '')
+            .join(' · ')}
+        </span>
+      </div>
+
+      <EncounterFiltersBar filters={filters} includeDeleted={includeDeleted} onChange={setFilters} patient={patient} />
+
+      <div className={styles.toolbar}>
+        <Checkbox
+          checked={includeDeleted}
+          id="include-deleted-encounters"
+          labelText={t('includeDeletedEncounters', 'Include deleted encounters')}
+          onChange={(_event, { checked }) => setIncludeDeleted(checked)}
+        />
+      </div>
+
+      {cannotIncludeDeleted ? (
+        <InlineNotification
+          className={styles.inlineNotification}
+          hideCloseButton
+          kind="warning"
+          lowContrast
+          subtitle={t(
+            'cannotIncludeDeletedEncounters',
+            'Deleted encounters can only be listed for a patient who has an identifier.',
+          )}
+          title={t('deletedEncountersUnavailable', 'Deleted encounters unavailable')}
+        />
+      ) : null}
+
+      {patientError ? (
+        <ErrorState error={patientError} headerTitle={t('encounters', 'Encounters')} />
+      ) : (
+        <Tabs
+          onChange={({ selectedIndex }) => onSelectView(patientRecordViews[selectedIndex])}
+          selectedIndex={Math.max(0, patientRecordViews.indexOf(view))}>
+          <TabList aria-label={t('auditViews', 'Audit views')}>
+            <Tab>{t('encounters', 'Encounters')}</Tab>
+            <Tab>{t('recordActivity', 'Patient activity')}</Tab>
+          </TabList>
+          <TabPanels>
+            <TabPanel>
+              <PatientEncounters
+                filters={filters}
+                includeDeleted={includeDeleted}
+                isLoadingPatient={isLoadingPatient}
+                onSelectEncounter={onSelectEncounter}
+                patient={patient}
+              />
+            </TabPanel>
+            <TabPanel>
+              <PatientActivity
+                filters={filters}
+                includeDeleted={includeDeleted}
+                onSelectEncounter={onSelectEncounter}
+                patient={patient}
+              />
+            </TabPanel>
+          </TabPanels>
+        </Tabs>
+      )}
+    </div>
+  );
+}

package/src/audit/patient-search.component.test.tsx

@@ -0,0 +1,73 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { SWRConfig } from 'swr';
+import { openmrsFetch } from '@openmrs/esm-framework';
+import PatientSearch from './patient-search.component';
+
+const mockOpenmrsFetch = jest.mocked(openmrsFetch);
+
+const mockPatients = [
+  {
+    uuid: 'patient-1',
+    display: 'Y2AHXV - Dave TestPatient',
+    identifiers: [{ uuid: 'id-1', identifier: 'Y2AHXV', preferred: true }],
+    person: { display: 'Dave TestPatient', gender: 'M', age: 42, birthdate: '1984-03-14T00:00:00.000+0000' },
+  },
+];
+
+function renderPatientSearch() {
+  const onSelectPatient = jest.fn();
+  render(
+    <SWRConfig value={{ dedupingInterval: 0, provider: () => new Map() }}>
+      <PatientSearch onSelectPatient={onSelectPatient} />
+    </SWRConfig>,
+  );
+  return onSelectPatient;
+}
+
+describe('<PatientSearch />', () => {
+  beforeEach(() => {
+    mockOpenmrsFetch.mockResolvedValue({
+      data: { results: mockPatients, totalCount: 1 },
+    } as unknown as ReturnType<typeof openmrsFetch>);
+  });
+
+  it('asks for a search term before searching', () => {
+    renderPatientSearch();
+
+    expect(screen.getByText(/enter a patient name or identifier/i)).toBeInTheDocument();
+    expect(mockOpenmrsFetch).not.toHaveBeenCalled();
+  });
+
+  it('searches patients by name or identifier and lists what it finds', async () => {
+    renderPatientSearch();
+
+    await userEvent.type(screen.getByRole('searchbox'), 'Y2AHXV');
+
+    expect(await screen.findByRole('button', { name: 'Dave TestPatient' })).toBeInTheDocument();
+    expect(screen.getByRole('cell', { name: 'Y2AHXV' })).toBeInTheDocument();
+    expect(screen.getByRole('cell', { name: '42' })).toBeInTheDocument();
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(expect.stringContaining('/ws/rest/v1/patient?q=Y2AHXV'));
+  });
+
+  it('drills down into the patient that is clicked', async () => {
+    const onSelectPatient = renderPatientSearch();
+
+    await userEvent.type(screen.getByRole('searchbox'), 'Y2AHXV');
+    await userEvent.click(await screen.findByRole('button', { name: 'Dave TestPatient' }));
+
+    expect(onSelectPatient).toHaveBeenCalledWith('patient-1');
+  });
+
+  it('says so when nothing matches', async () => {
+    mockOpenmrsFetch.mockResolvedValue({ data: { results: [], totalCount: 0 } } as unknown as ReturnType<
+      typeof openmrsFetch
+    >);
+    renderPatientSearch();
+
+    await userEvent.type(screen.getByRole('searchbox'), 'nobody');
+
+    expect(await screen.findByText(/no patients match "nobody"/i)).toBeInTheDocument();
+  });
+});