FHIR sandbox guide

The sandbox is a small, local FHIR R4 server, written in plain JavaScript, loaded with synthetic patients and observations. It lives in practice-repo/fhir-sandbox/, and its server is practice-repo/fhir-sandbox/server.js. Its README is the source of truth for data and commands. This guide is the learner's walk-through.

It needs only Node.js, which you already have for the practice repository. There is no Docker, no Java, and nothing else to install.

Everything in the sandbox is synthetic. NHS numbers are from the 999 range reserved for testing. Never put real patient data into it, even briefly.

It is a teaching server, not a real one. It supports Patient, Observation, and StructureDefinition, and only the parts of the FHIR REST API the course uses.

1. Start and stop

From practice-repo/:

npm run fhir     # start the sandbox at http://localhost:8080/fhir

It prints its address and how many resources it loaded. It loads the training profile and the synthetic data every time it starts, and keeps everything in memory, so a restart puts the data back as it was. Stop it with Ctrl+C.

You do not need to start it before running the API tests: if FHIR_BASE_URL is not set, the tests start it for you.

2. Look around by hand first

Before writing tests, explore the API the way a manual tester would. Start the sandbox, then use a browser or curl:

Write down what each returns. This is the manual test you are about to automate.

The sandbox supports:

3. Run the example suite

From practice-repo/:

npm run test:api

The suite is practice-repo/tests/api/fhir.test.js: Mocha tests that call the sandbox with Node's built-in fetch. If the server cannot be reached, every test fails with a connection error. That is an environment problem, not a product defect: read the message, then see Troubleshooting.

The base URL comes from FHIR_BASE_URL, defaulting to http://localhost:8080/fhir. Set it only to point the tests at a different server, such as a shared team test server with synthetic data (Decision 4).

4. What the example suite covers

5. Write your own

Write your tests in a new file in practice-repo/tests/api/, for example my-fhir.test.js. Do not edit the example suite. Use the example's helpers as a model: a syntheticPatient() data builder with overrides, and checks on OperationOutcome issues.

A test looks like this:

import { strict as assert } from 'node:assert';

const BASE = process.env.FHIR_BASE_URL ?? 'http://localhost:8080/fhir';

describe('Patient read', () => {
  it('returns the synthetic adult', async () => {
    const response = await fetch(`${BASE}/Patient/synthetic-adult`, {
      headers: { Accept: 'application/fhir+json' },
    });
    assert.equal(response.status, 200);
    const patient = await response.json();
    assert.equal(patient.resourceType, 'Patient');
    assert.equal(patient.identifier[0].value, '9990010005');
  });
});

The Evidence 12 requirements, by track:

Every test must fail when the behaviour is wrong. Show it once, as in Module 11.

6. Band 7 test engineering: partner system simulator

Write a small simulator for a partner system that sends observations to your service, for example a stub HTTP server built with Node's node:http module that returns a canned FHIR Bundle, with one normal case and one malformed case. Use it to test how your code handles both, without depending on the real partner. The sandbox's own server.js is a worked example of a small Node.js HTTP server. Record in your suite's spec what the simulator does and does not cover.

7. Troubleshooting

View this document on GitHub materials/modules/module-12-api-integration-fhir/fhir-sandbox-guide.md