Quick answer: Test JSON configuration imports in the same Node.js runtime you deploy. Check the required import attribute, the shape of the default export, whether consumers share a mutable object, and whether changing the file requires an explicit reread. These are different failures even when all the input files contain valid JSON.
A setting changes on disk, but the service keeps using the old value. Before changing your deployment process, test whether the application is reading a file or importing a cached module. The fixtures below run on Node.js v24.22.1 without a bundler.
1. How do you test that a JSON import declares the right attribute?
Test the same fixture with and without the JSON type attribute. In Node.js v24, the import without the attribute should reject with the missing attribute error, while the import with it should succeed. That paired check distinguishes a loader requirement from bad JSON syntax or a missing file.
Create a scratch directory with the following file named settings.json. Run each JavaScript block as its own .mjs file beside that fixture. The last test changes the fixture and restores it in a finally block. Keep these examples away from real configuration and credentials.
{"region":"test","retry":{"limit":2}}
import assert from 'node:assert/strict';
await assert.rejects(import('./settings.json'), {
code: 'ERR_IMPORT_ATTRIBUTE_MISSING',
});
const { default: settings } = await import('./settings.json', {
with: { type: 'json' },
});
assert.equal(settings.region, 'test');
The Node.js v24 import attribute reference shows the static and dynamic forms. The dynamic form is handy here because the assertion can catch a rejected promise. A static import can fail while the module is loading, before any statements in that file execute. To test an application entry point that uses static imports, run it as a subprocess and assert its exit status as well as a useful error message. For background on the language itself, see Wikipedia’s JavaScript overview.
If your editor accepts the syntax but production rejects it, test the artifact the runtime actually executes. A bundler might replace the import with an inlined value; a development server might use a different Node version than the production container. Neither success tells you whether the deployed loader will accept the original statement. Use the runtime version printed by the process that starts your service when investigating the mismatch.
Keep the missing attribute case isolated from your content tests. A fixture with an invalid path, a missing attribute, and a malformed document can fail for several reasons. One small negative case and one positive control give you a signal you can act on. For syntax troubleshooting after the loader starts reading the file, see the JavaScript JSON parsing and serialization guide.
2. How do you test the default export against your configuration contract?
Import the default value and check the fields the application needs, including their types and any required limits. Node.js does not turn JSON properties into named module exports or enforce your application's configuration rules. A successful import only establishes that the loader could return a value from the document.
import assert from 'node:assert/strict';
import settings from './settings.json' with { type: 'json' };
function accepts(value) {
return value !== null && typeof value === 'object' &&
!Array.isArray(value) && typeof value.region === 'string' &&
Number.isInteger(value.retry?.limit) &&
value.retry.limit >= 0 && value.retry.limit <= 5;
}
assert.ok(accepts(settings));
assert.equal(accepts({ region: 'test', retry: { limit: '2' } }), false);
assert.equal(accepts([]), false);
assert.equal(accepts({ region: 'test' }), false);
The Node.js JSON module documentation specifies the default export. Think of importing the value and reading a field as separate operations. If a developer tries to import the region as a named binding, fixing that statement still leaves the question of whether the region field is present and suitable for the application. The example uses a deliberately small policy: it permits a string region and a retry limit between zero and five. Those limits belong to the sample application.
Open the synthetic fixture in the JSON Viewer tree to locate the nested retry object and inspect the value stored under limit. The viewer helps you see the structure. Keep the check for an integer and the accepted range in executable code, where it can run on every deployment. If the format grows beyond a handful of rules, the JSON Schema introduction explains how to describe required fields and constraints explicitly.
Include at least one negative fixture that looks plausible in review. A numeric string often looks close enough to a number when the surrounding document is familiar, but accepting it can change how the caller calculates delays or compares counts. Decide whether coercion belongs in your configuration pipeline and test that decision. If it does, test the normalization separately from whether the original data satisfies the input contract. That keeps a future convenience conversion from silently broadening what the application accepts.
3. How do you detect mutation shared between JSON import consumers?
Load the same JSON module twice, then change a nested value through one reference and check what the other sees. If both consumers share the cached object, the change is visible through both references. Add a separate test for any copy your application promises to give callers before they mutate settings.
import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import settings from './settings.json' with { type: 'json' };
const require = createRequire(import.meta.url);
const other = require('./settings.json');
assert.equal(other, settings);
const copy = structuredClone(settings);
settings.retry.limit = 4;
assert.equal(other.retry.limit, 4);
assert.equal(copy.retry.limit, 2);
This test checks the direction documented by Node.js: after importing a JSON module, CommonJS can receive the same object from the same file. It uses a static import so that evaluation has already loaded the JSON before the call to require. The mutation is confined to the test process and does not rewrite the file. Use strict identity for the first assertion; deep equality would also pass for two independent objects with identical initial contents.
A practical failure looks like a test that passes on its own and fails after another test runs. If the first test overwrites a nested retry limit on the shared object, the second test starts from the altered value even though the fixture file has never changed. Avoid relying on cleanup between application consumers. If they need editable data, expose a loader function that hands out an independent copy, and test two callers that change the same nested field to different values. A shallow copy of the root object is insufficient for that specific promise because both copies can still share the nested retry object.
A separate case is configuration that nobody should edit at all. Keep the imported value private, publish only the fields a caller needs, and avoid passing writable nested references across that boundary. Choose a strategy that matches the existing application rather than combining cloning and shared state by accident. Use the configuration file mistakes guide for related decisions about defaults, overrides, and which settings belong in a file.
4. How do you test whether a configuration change is reread from disk?
Import a fixture, update it on disk, and compare a repeated import with an explicit read and parse. Reusing the same resolved module can return the original object, whereas an explicit read can see the replacement file. Use this test to choose between configuration loaded at startup and deliberate runtime reloads.
import assert from 'node:assert/strict';
import { readFile, writeFile } from 'node:fs/promises';
const file = new URL('./settings.json', import.meta.url);
const original = await readFile(file, 'utf8');
const options = { with: { type: 'json' } };
const first = (await import(file.href, options)).default;
try {
await writeFile(file, '{"region":"updated","retry":{"limit":3}}');
const cached = (await import(file.href, options)).default;
const fresh = JSON.parse(await readFile(file, 'utf8'));
assert.equal(cached, first);
assert.equal(cached.region, 'test');
assert.equal(fresh.region, 'updated');
} finally {
await writeFile(file, original);
}
The Node.js file system reference documents the read operation. Resolving the file relative to the module makes the experiment independent of the shell's working directory. Using the same file URL both times also matters: the point of the comparison is to hold module identity constant while changing the bytes on disk. The test is sequential and uses a disposable local file. It does not establish that concurrent readers see consistent content during a production write.
Before implementing a reload, choose who owns the active settings. One workable model is to read the replacement into a candidate, parse it, validate it, and only then swap the active value. If a new file is malformed, decide whether the service should retain the previous valid settings or stop. Test whichever behavior the application promises, including what it logs without exposing sensitive values. An explicit file read gives you new bytes; it does not guarantee that a partially written file, conflicting edit, or wrong deployment path is safe.
For settings that should change only on restart, the cache is useful. Test that startup reads a known fixture and rejects incompatible values before any dependent component starts. For settings that must change without a restart, keep a reload test at the file boundary and a separate integration test that proves a real consumer uses the new value. A changed object in a loader test is not proof that a client already holding the old object will update. Keeping those checks separate makes a stale setting easier to trace to the exact step that missed the change.
A reload test benefits from two versions of the same fixture whose values lead to different outcomes. For example, a retry limit of two and a retry limit of three let a caller exercise a branch that should change after the update. If you test only that the loader returns an object, both versions look like success. If you compare only a timestamp, an unrelated touch to the file can also look like success. Assert the actual field the consumer needs and the action that should follow from it.
If several processes run the same service, a successful reload in one process does not imply that the others have reloaded. Each may read the file at a different time, and some may see a different mounted path. The local fixture intentionally keeps those variables out of the test. For a distributed rollout, add a separate check of the effective configuration version in each process without logging the whole file. Use a nonsecret revision marker if you need an easy way to tell which settings are active.
Finally, keep loader failures distinct from application validation failures in your diagnostics. A missing attribute points to the import statement or runtime. An invalid retry value points to a configuration contract. A changed file paired with an unchanged import points to the loading strategy. Those signals give the person responding to an incident a narrower place to start.