@fluid-internal/mocha-test-setup

IMPORTANT: Fluid Framework uses this package as an implementation detail. Do not use it as a public dependency. We do not guarantee the stability of this package or its APIs.

This package has a few main purposes:

• Expose/generate a default .mocharc.cjs configuration for running mocha tests, which other packages can extend.
• Add mocha beforeAll, beforeEach and afterEach root hook plugins to add some special behavior when we run tests.

Running tests

For packages using this configuration, build the package and its tests, then run pnpm exec mocha from the package directory.

• Select test files with MOCHA_SPEC.
• Filter test names with Mocha's --fgrep or --grep.
• Enable performance measurements with FLUID_TEST_PERF_MODE.

Environment Variables

Set environment variables before running Mocha. For cross-platform scripts, use cross-env, for example pnpm exec cross-env MOCHA_SPEC=lib/test/example.spec.js mocha.

MOCHA_SPEC

Sets the compiled test file, directory, or glob to load, relative to the package directory. It replaces the default selection of lib/test (or dist/test with FLUID_TEST_MODULE_SYSTEM=CJS). Unlike MOCHA_SPEC, positional file arguments and --spec add to the configured selection because of Mocha's configuration merging. Name filtering alone still loads all configured test files; use MOCHA_SPEC to avoid loading unrelated files.

FLUID_TEST_PERF_MODE

Set to 1 to measure benchmarks instead of running them as correctness tests. Leave unset for correctness testing; do not use 0 to disable it.

This selects the benchmark reporter, sets a 1,000-second timeout per test, and writes results to ./benchmarkOutput.json. Override the timeout with FLUID_TEST_TIMEOUT and the report path with --reporterOptions reportFile=<path>.

The default @Benchmark filter is omitted when you supply --fgrep <text> or --grep <pattern> (use these long options with separate arguments). Your filter replaces, rather than intersects with, the default. See benchmark filtering for tags and combining constraints.

FLUID_TEST_TIMEOUT

Overrides Mocha's per-test timeout in milliseconds, including the performance-mode default.

FLUID_TEST_FORBID_ONLY

When present, enables Mocha's forbid-only option to reject exclusive tests.

FLUID_TEST_MODULE_SYSTEM

When set to "CJS", current run is setup to be for CommonJS coverage:

• "CJS" is noted as a variant and shown as prefix to test case names.
• The JUnit test-results file will be prefixed with "CJS-".
• Default spec is changed from lib/test to dist/test.

FLUID_LOGGER_PROPS

Sets a JSON object serialized into the testEnvProps telemetry field. Its hostName property also overrides the event's hostName:

FLUID_LOGGER_PROPS='{ "hostName": "Benchmark" }'

FLUID_TEST_LOGGER_PKG_SPECIFIER

Specifies a module exporting createTestLogger, which returns an ITelemetryBufferedLogger. The setup calls this factory, wraps the logger with test context, and installs the global getTestLogger function. Use this variable rather than --require to configure a custom logger. Pipelines use it to send telemetry to internal engineering systems.

Base mocharc.cjs configuration

To leverage the base mocha configuration exposed by this package, first add it as a devDependency to your package.json (the rest of the file has been omitted):

{
    "devDependencies": {
        "@fluid-internal/mocha-test-setup": "version-that-matches-the-rest-of-the-release-group"
    }
}

Then put this in a .mocharc.cjs file at the root of your package:

"use strict";

const getFluidTestMochaConfig = require("@fluid-internal/mocha-test-setup/mocharc-common");

const config = getFluidTestMochaConfig(__dirname);
module.exports = config;

If you need extra configuration, make changes to the config object before assigning it to module.exports.

Mocha will use this file by default if no path to a configuration file is provided explicitly.

The following excerpt shows some of the settings generated by getFluidTestMochaConfig():

{
  "recursive": true,
  "require": ["@fluid-internal/mocha-test-setup", "source-map-support/register"], // can be extended by providing additionalRequiredModules to getFluidTestMochaConfig()
  "unhandled-rejections": "strict",
  "node-option": ["conditions=allow-ff-test-exports", "expose-gc"],
  "ignore": [ "**/*.tool.{js,cjs,mjs}" ], // Ignore "tools" which are scripts intended to be run, not part of the test suite.
  "spec": "lib/test" // Defaults to "lib/test" where esm tests typically are. Can be overridden via MOCHA_SPEC.
};

It is recommended that the source for tests files use a file name ending in ".spec.ts", but this is not enforced: no file named based filtering of test files is done by default, except for the ignoring of "**/*.tool.{js,cjs,mjs}" noted above.

Note: some packages do explicitly filter test files to *.spec.js: in such packages test files with other names will be silently ignored.

Special behavior

Suppress console output by default

console.log(), console.warn() and console.error() are suppressed during tests unless FLUID_TEST_VERBOSE is set, for example FLUID_TEST_VERBOSE=1.

Telemetry events

A couple of telemetry events fluid:telemetry:Test_start and fluid:telemetry:Test_end will be generated for each test. The Test_end event includes fields with the test's state (passing/failed), its duration, if it timed out. If a FLUID_TEST_VARIANT environment variable exists, the testVariant field in the events will have its value.

Contribution Guidelines

You can contribute to Fluid Framework in these ways:

• Answer questions in GitHub Discussions.
• Submit bug reports and help verify fixes.
• Review source code changes.
• Contribute bug fixes.

For detailed instructions, read the repo documentation.

This project follows the Microsoft Open Source Code of Conduct. For more information, read the Code of Conduct frequently asked questions. For questions or comments, contact [email protected].

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.

Help

Read the Fluid Framework documentation for information about Fluid Framework concepts and APIs.

To request information that the documentation does not contain, create an issue.

Trademark

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.

Use of these trademarks or logos must follow Microsoft's Trademark & Brand Guidelines.

Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.