{"id":12957,"library":"cht-conf-test-harness","title":"CHT Configuration Test Harness","description":"The `cht-conf-test-harness` is a JavaScript/TypeScript test framework designed specifically for validating configurations of applications built on the Community Health Toolkit (CHT) Core Framework. It simulates a CHT application instance, allowing developers to write and run automated tests against their app configurations without deploying to a live environment. The current stable version is 5.0.4, with frequent minor releases addressing bug fixes and major versions typically aligning with significant updates to the CHT Core Framework. A key differentiator is its explicit compatibility matrix, ensuring tests can target and validate against specific CHT Core versions (e.g., v5.x supports CHT Core 4.11.x+). It is commonly used with testing frameworks like Mocha and assertion libraries like Chai.","status":"active","version":"5.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/medic/cht-conf-test-harness","tags":["javascript"],"install":[{"cmd":"npm install cht-conf-test-harness","lang":"bash","label":"npm"},{"cmd":"yarn add cht-conf-test-harness","lang":"bash","label":"yarn"},{"cmd":"pnpm add cht-conf-test-harness","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used assertion library alongside the test harness for writing test expectations.","package":"chai","optional":true},{"reason":"Popular test runner often used to execute tests defined with cht-conf-test-harness.","package":"mocha","optional":true}],"imports":[{"note":"The primary class for instantiating the test environment. It is a named export in ESM contexts. The CJS equivalent uses `TestRunner` as the default export.","wrong":"import TestHarness from 'cht-conf-test-harness';","symbol":"TestHarness","correct":"import { TestHarness } from 'cht-conf-test-harness';"},{"note":"This is the CommonJS default export, typically instantiated as `new TestRunner()`. For ESM, use the named export `TestHarness`.","wrong":"import { TestRunner } from 'cht-conf-test-harness';","symbol":"TestRunner","correct":"const TestRunner = require('cht-conf-test-harness');"},{"note":"While used in test harness examples, `expect` typically comes from a separate assertion library like Chai, which is a common companion dependency.","wrong":"import { expect } from 'cht-conf-test-harness';","symbol":"expect","correct":"import { expect } from 'chai';"}],"quickstart":{"code":"import { TestHarness } from 'cht-conf-test-harness';\nimport { expect } from 'chai';\n\ndescribe('CHT Configuration Tests', () => {\n  let harness;\n\n  before(async () => {\n    harness = new TestHarness({\n      // Optional: Specify CHT Core version to simulate\n      coreVersion: '4.11', \n      // Optional: Launch browser with GUI for debugging\n      headless: true, \n      verbose: false\n    });\n    await harness.start(); // Initializes the simulated CHT environment\n  });\n\n  after(async () => {\n    await harness.stop(); // Cleans up the environment\n  });\n\n  beforeEach(async () => {\n    await harness.clear(); // Clears all data before each test\n  });\n\n  afterEach(() => {\n    // Ensure no unexpected console errors occurred during form evaluation\n    expect(harness.consoleErrors).to.be.empty;\n  });\n\n  it('should load a specific form successfully', async () => {\n    const formName = 'patient_registration_form';\n    await harness.loadForm(`app/${formName}`);\n    expect(harness.state.pageContent).to.include(`id=\"${formName}\"`);\n  });\n\n  it('should allow filling a form and verify report output', async () => {\n    const formName = 'delivery_report';\n    // Simulate filling the form with specific inputs\n    const result = await harness.fillForm(formName, [\n      'patient_name:Jane Doe',\n      'delivery_outcome:live_birth'\n    ]);\n\n    // Verify form submission was successful and check report fields\n    expect(result.errors).to.be.empty;\n    expect(result.report.fields.patient_name).to.equal('Jane Doe');\n    expect(result.report.fields.delivery_outcome).to.equal('live_birth');\n  });\n});","lang":"typescript","description":"This quickstart demonstrates how to set up, run, and clean up a CHT test harness instance using Mocha and Chai. It shows loading a form, simulating user input to fill a form, and asserting on the generated report data and console errors."},"warnings":[{"fix":"Upgrade your CHT Core Framework to version 4.11 or later, or remain on `cht-conf-test-harness` v4.x if testing older CHT Core versions is necessary.","message":"Version 5.0.0 of `cht-conf-test-harness` introduced breaking changes by dropping support for CHT Core 4.6 and older, and adding support exclusively for CHT Core 4.11 and newer. Configurations for older CHT Core versions will no longer be compatible or testable with `cht-conf-test-harness` v5.x.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure your environment has all Puppeteer's required system dependencies. For Docker/CI, use a base image that includes these browser dependencies, or install them explicitly (e.g., `apt-get install -y libatk-bridge2.0-0 libgbm-dev`). Consider setting `headless: true` or `args: ['--no-sandbox', '--disable-setuid-sandbox']` in the harness options for CI environments.","message":"The `cht-conf-test-harness` relies on Puppeteer internally, which can sometimes fail to launch the browser process, especially in CI/CD environments or environments without necessary browser dependencies (e.g., `libatk-bridge2.0-0`, `libgbm-dev`).","severity":"gotcha","affected_versions":">=2.x"},{"fix":"Install `mocha` and `chai` as dev dependencies: `npm install --save-dev mocha chai`. Configure your `package.json` scripts to run Mocha, e.g., `\"test\": \"mocha --require @babel/register your-tests/**/*.js\"` (adjusting for your transpilation needs).","message":"While `cht-conf-test-harness` provides the testing environment, it does not include a test runner or assertion library itself. Users must explicitly install and integrate frameworks like Mocha and assertion libraries like Chai to write and execute their tests effectively.","severity":"gotcha","affected_versions":">=2.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install necessary browser dependencies (e.g., `libatk-bridge2.0-0`, `libgbm-dev` on Debian-based systems) or add `--no-sandbox` arguments to Puppeteer options if running in a trusted containerized environment.","cause":"Puppeteer, used internally, could not start a browser instance due to missing system dependencies or sandbox issues in certain environments (e.g., Docker, CI).","error":"Error: Failed to launch the browser process!"},{"fix":"For CommonJS, use `const TestRunner = require('cht-conf-test-harness');`. For ESM, use the named import `import { TestHarness } from 'cht-conf-test-harness';` and instantiate `new TestHarness()`.","cause":"Attempting to import `TestRunner` using ESM syntax (`import { TestRunner } from '...'`) when it is primarily a CommonJS default export or the default export is not named `TestRunner` in ESM.","error":"TypeError: TestRunner is not a constructor"},{"fix":"Install `chai` (`npm install --save-dev chai`) and import `expect` explicitly in your test files: `import { expect } from 'chai';`.","cause":"The `expect` assertion function is being used without being imported or correctly linked from an assertion library.","error":"expect is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}