cfg-test.js

In-source testing using Node.js Test Runner

• Requirements
• Install
• Setup
• Examples
• Production Build
  • ESBuild
  • Vite
  • Rollup
  • Webpack
• Configuration (Optional)

Requirements

Node.js >=18.19.0

Install

npm i -D cfg-test \
  @swc-node/register \
  @types/node \
  typescript

Setup

// src/lib.ts

// the implementation
export function addOne(a: number): number {
  return a + 1
}

// in-source test suites
if (cfgTest && cfgTest.url === import.meta.url) {
  const { assert, describe, test } = cfgTest

  describe("addOne", () => {
    test("it works", () => {
      assert.equal(addOne(2), 3)
    })
  })
}

// @types/global.d.ts

/// <reference types="cfg-test/globals" />

// tsconfig.json

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
  },
  "include": [
    "@types",
    "src",
  ],
}

// package.json

{
  "type": "module",
  "scripts": {
    "test": "node --import cfg-test --test ./src/lib.ts"
  },
  "devDependencies": {
    "@swc-node/register": "latest",
    "@types/node": "latest",
    "cfg-test": "latest",
    "typescript": "latest"
  }
}

Then you can start to test.

npm test

Examples

|Node.js|Transpiler|Type |Link | |:------|:---------|:-------|:---------------------------------------------------------| |^18.19 |swc |ESM |examples/node18/swc/esm | | | |CommonJS|examples/node18/swc/cjs | | |ts-node |ESM |examples/node18/ts-node/esm| | | |CommonJS|examples/node18/ts-node/cjs| |^20.0 |swc |ESM |examples/node20/swc/esm | | | |CommonJS|examples/node20/swc/cjs | | |ts-node |ESM |examples/node20/ts-node/esm| | | |CommonJS|examples/node20/ts-node/cjs| |^21.0 |swc |ESM |examples/node21/swc/esm | | | |CommonJS|examples/node21/swc/cjs | | |ts-node |ESM |examples/node21/ts-node/esm| | | |CommonJS|examples/node21/ts-node/cjs|

Production Build

import {
  // {
  //   NODE_ENV: "test",
  //   CFG_TEST: "true",
  // }
  testEnv,

  // {
  //   CFG_TEST: "false",
  //   CFG_TEST_URL: undefined,
  //   CFG_TEST_FILE: undefined,
  //   CFG_TEST_WATCH: "false",
  // }
  buildEnv,

  // {
  //   "process.env.NODE_ENV": "\"test\"",
  //   "process.env.CFG_TEST": "\"true\"",
  // }
  testDefine,

  // {
  //   cfgTest: "undefined",
  //   "process.env.CFG_TEST": "\"false\"",
  //   "process.env.CFG_TEST_URL": "undefined",
  //   "process.env.CFG_TEST_FILE": "undefined",
  //   "process.env.CFG_TEST_WATCH": "\"false\"",
  // }
  buildDefine,
} from "cfg-test/define"

ESBuild

import { buildDefine } from "cfg-test/define"
import { build } from "esbuild"

build({
  define: {
    ...buildDefine,
    "process.env.NODE_ENV": "\"production\"",
  },
  // other options
})

Vite

// vite.config.ts

import { buildDefine } from "cfg-test/define"
import { defineConfig } from "vite"

export default defineConfig({
  define: {
    ...buildDefine,
    "process.env.NODE_ENV": "\"production\"",
  },
  // other options
})

Rollup

// rollup.config.js

import replace from "@rollup/plugin-replace"
import { buildDefine } from "cfg-test/define"

export default {
  plugins: [
    replace({ 
      ...buildDefine,
      "process.env.NODE_ENV": "\"production\"",
    }),
  ],
  // other options
}

Webpack

import { buildDefine } from "cfg-test/define"

const definePlugin = new webpack.DefinePlugin({
  ...buildDefine,
  "process.env.NODE_ENV": "\"production\"",
})

Configuration

Loaders can be added via the configuration file.

Specify the path to the configuration file in the environment variable CFG_TEST_CFG. The default value is a comma-separated list of paths: config/cfg-test/config, config/cfg-test, and cfg-test.

// .config/cfg-test.json, .config/cfg-test/config.json,
// config/cfg-test.json, config/cfg-test/config.json, cfg-test.json
// or process.env.CFG_TEST_CFG="<your-config-path>"

{
  // Additonal environment variables
  "env": {
    "MY_CUSTOM_ENV": "true"
  },
  "globals": {
    // Additional global variables
    "__DEV__": true
  },
  // Additional require modules
  "require": [
    "./path/to/require.js"
  ],
  // Additional import modules
  "import": [
    "./path/to/import.js"
  ]
}