JSON Patch Test Suite

Common errors

• Cannot find module 'json-patch-test-suite/tests.json'

  cause Your TypeScript configuration or JavaScript bundler is not set up to correctly resolve `.json` file imports, or the module resolution path is incorrect.
  fix For TypeScript, add `"resolveJsonModule": true` and `"esModuleInterop": true` to the `compilerOptions` in your `tsconfig.json`. If using a bundler (like Webpack), ensure your configuration includes a JSON loader (often enabled by default). Double-check the exact import path: `import tests from 'json-patch-test-suite/tests.json'`.

• SyntaxError: Unexpected token '{' at <module-path>/node_modules/json-patch-test-suite/tests.json

  cause This typically occurs in older Node.js or CommonJS environments when `require()` or `import` attempts to parse a JSON file as a JavaScript module, or if the `require()` call does not specify the full `.json` extension.
  fix Ensure that your `require()` call explicitly targets the `.json` file extension (e.g., `const tests = require('json-patch-test-suite/tests.json')`). If using ESM in Node.js, confirm your `package.json` contains `"type": "module"` or use the `.mjs` extension for your module files, and configure your bundler/TypeScript to resolve JSON modules.

Warnings

• gotcha Direct JSON file imports require specific configuration in modern JavaScript environments.
  Fix: For TypeScript projects, ensure `"resolveJsonModule": true` and `"esModuleInterop": true` are set in your `tsconfig.json`'s `compilerOptions`. When using bundlers (e.g., Webpack, Rollup, Parcel), verify they are configured to handle JSON file imports (often built-in). For Node.js ESM, ensure your `package.json` specifies `"type": "module"` or use `.mjs` files for ESM modules.
• gotcha The `error` field in test records provides a *suggested* error message, not a definitive string for comparison.
  Fix: JSON Patch implementations may produce varying error messages. When `test.error` is present, focus on verifying that *an* error is thrown by your patching logic, rather than performing a strict string equality comparison against the `test.error` value. You might check for the *type* of error or a partial match for robustness.
• gotcha This package provides only JSON Patch test data, not an implementation of the RFC 6902 specification.
  Fix: Developers must integrate this test suite with their own JSON Patch library (e.g., `fast-json-patch`, `json-patch-js`) to actually apply the patches and validate the results. The quickstart example illustrates how to provide a placeholder `applyPatch` function that you would replace with your library's actual function.

Install

• npm install json-patch-test-suite npm
• yarn add json-patch-test-suite yarn
• pnpm add json-patch-test-suite pnpm

Imports

• tests
  wrong:

  import { tests } from 'json-patch-test-suite'

  correct:

  import tests from 'json-patch-test-suite/tests.json'

  For ESM projects, import the `.json` file directly. Requires `"resolveJsonModule": true` in `tsconfig.json` (for TypeScript) or appropriate bundler configuration (e.g., Webpack, Rollup) to recognize JSON imports.
• specTests
  wrong:

  const specTests = require('json-patch-test-suite')

  correct:

  import specTests from 'json-patch-test-suite/spec_tests.json'

  The `spec_tests.json` file contains test cases specifically derived from the RFC6902 specification document itself. It follows the same import patterns as `tests.json`.
• tests
  wrong:

  const tests = require('json-patch-test-suite')

  correct:

  const tests = require('json-patch-test-suite/tests.json')

  For CommonJS projects, use `require()` with the full, explicit path to the `.json` file. Node.js correctly handles `require()` of JSON files by parsing them directly.

Quickstart

This quickstart demonstrates how to load the `tests.json` file from the `json-patch-test-suite` package and iterate through each test record. It shows how to integrate the test data with a hypothetical `applyPatch` function (which you would replace with your actual JSON Patch implementation) to validate its behavior against the suite's expected outcomes or errors. The example uses Node.js `fs` and `path` for file loading.

import * as fs from 'fs';
import * as path from 'path';

// IMPORTANT: This 'applyPatch' function is a placeholder.
// You must integrate your actual JSON Patch implementation here
// (e.g., from 'fast-json-patch', 'json-patch', etc.)
const applyPatch = (doc: any, patch: any[]): any => {
  // In a real scenario, this would apply the patch and return the new document.
  // For this example, we'll simulate a success or throw an error based on patch content.
  if (!doc || !patch) throw new Error('Invalid input for patch application.');
  if (patch.some((op: any) => op.path === '/invalid/path' && op.op === 'add')) {
    throw new Error('Simulated patch error: Invalid path operation.');
  }
  return { ...doc, patched: true }; // Simulate a successful patch
};

interface TestRecord {
  doc: any;
  patch: any[];
  expected?: any;
  error?: string;
  comment?: string;
  disabled?: boolean;
}

// Dynamically resolve the path to the installed json-patch-test-suite package.
// This is generally safer than assuming 'node_modules' directly.
const resolvePackagePath = (packageName: string) => {
  try {
    return path.dirname(require.resolve(packageName + '/package.json'));
  } catch (e) {
    throw new Error(`Could not find package ${packageName}. Is it installed?`);
  }
};

const suitePackagePath = resolvePackagePath('json-patch-test-suite');
const testsPath = path.join(suitePackagePath, 'tests.json');

const testSuite: TestRecord[] = JSON.parse(fs.readFileSync(testsPath, 'utf8'));

let passedTests = 0;
let failedTests = 0;

console.log(`Running ${testSuite.length} JSON Patch tests from the suite...\n`);

testSuite.forEach((test, index) => {
  if (test.disabled) {
    // console.log(`Skipping disabled test [${index + 1}]: ${test.comment}`);
    return;
  }

  try {
    const result = applyPatch(test.doc, test.patch);

    if (test.expected !== undefined) {
      if (JSON.stringify(result) === JSON.stringify(test.expected)) {
        passedTests++;
      } else {
        failedTests++;
        console.error(`FAIL [${index + 1}]: ${test.comment || 'Unnamed test'}`);
        console.error('  Doc:', JSON.stringify(test.doc));
        console.error('  Patch:', JSON.stringify(test.patch));
        console.error('  Expected:', JSON.stringify(test.expected));
        console.error('  Got:', JSON.stringify(result));
        console.error('--------------------------------------------------');
      }
    } else if (test.error !== undefined) {
      failedTests++;
      console.error(`FAIL [${index + 1}]: ${test.comment || 'Unnamed test'} (Expected error, but patch succeeded)`);
      console.error('--------------------------------------------------');
    }
    // If no expected/error, assume success if no exception
  } catch (e: any) {
    if (test.error !== undefined) {
      passedTests++; // We expected an error, and got one. Good enough for basic check.
    } else {
      failedTests++;
      console.error(`FAIL [${index + 1}]: ${test.comment || 'Unnamed test'} (Unexpected error)`);
      console.error('  Error:', e.message);
      console.error('  Doc:', JSON.stringify(test.doc));
      console.error('  Patch:', JSON.stringify(test.patch));
      console.error('--------------------------------------------------');
    }
  }
});

console.log(`\nTests finished: ${passedTests} passed, ${failedTests} failed.`);
if (failedTests > 0) {
  process.exit(1);
}