README.md

xunit.ts

A TypeScript unit testing framework, following standard xUnit patterns

Documentation

Detailed documentation is available at https://ecoAPM.github.io/xunit.ts

Quick Start

Requirements

• Node.js 14+

  (other versions may work, but only the latest minor release for each current/active/maintenance LTS version is supported)

• A supported TypeScript compiler

  • TypeScript (v4, v5)
  • Vite (v2, v3, v4, v5, v6)
  • Rollup (v2, v3, v4)
  • Parcel (v1, v2)
  • Webpack (v5)

Note that 1.4.0 is the last release that will support legacy versions of the above; v2.0 (expected Q1 2025) will support:

• Node.js 18+
• TypeScript 5+
• Vite 6+
• Rollup 4+
• Parcel 2+
• Webpack 5+

Ongoing commercial support for legacy versions is available for Corporate, Premier, and Title Sponsors.

Installation

npm install --dev xunit.ts

or

yarn add --dev xunit.ts

Configure your test project

At a minimum, your tsconfig.json will require the following:

{
	"compilerOptions": {
		"target": "ES2015", //or "ES6"
		"module": "CommonJS",
		"experimentalDecorators": true
	}
}

If you're using a bundler, you'll need to declare xunit.ts as an external in your build config file for the tests to be detected. See the officially-supported configurations in the compiler-tests directory of the source code for detailed examples.

Create your first test

MyTestSuite.ts:

import { Test, TestSuite } from 'xunit.ts';

export default class MyTestSuite extends TestSuite {
	@Test()
	async MyFirstTest() {
		this.assert.equal(2, 1 + 1);
	}
}

Run your tests

You'll first need to compile your TypeScript tests into JavaScript using tsc or the supported bundler of your choice.

Then run:

npm run xunit compiled_tests_dir

or

yarn xunit compiled_tests_dir

to run the tests.

You can also run xunit.ts from a script in your package.json:

{
	"scripts": {
		"test": "tsc --outDir compiled_tests_dir && xunit compiled_tests_dir"
	}
}

Filtering tests

The xunit command can take one or more --filter flags (-f alias) followed by a regular expression to match TestSuiteName.TestMethodName. See the full documentation for more details.

Output

Console

By default, xunit.ts will output test results to stdout so they can be captured by your terminal, or piped elsewhere:

~/example $ npm run test

My Test Suite
  ✓ My First Test

    Passed: 1
     Total: 1

~/example $ _

Results can also be output in JUnit and Sonar XML formats, for import into other systems. See the full documentation for a list of all available output options.

Assertions

xunit.ts has a built-in assertion library, accessible via this.assert... from within a TestSuite, or you can use your favorite third-party one: anything that uses Node.js' AssertionError is supported.

If you prefer, you can import { Assert } from 'xunit.ts and call e.g. Assert.true(expression); instead of this.assert.true(expression); for any included assertion.

See the full documentation for a list of all available assertions.

Contributing

Please be sure to read and follow ecoAPM's Contribution Guidelines when submitting issues or pull requests.

Building / Testing locally

From the core directory:

1. npm install or yarn install to download all dependencies
2. npm run build or yarn build will compile xunit.ts and its tests to the dist directory
3. npm run test or yarn test will run all unit tests in dist/tests
4. npm run build && npm run test or yarn build && yarn test will build and run tests in a single step

Missing an assertion?

Create an issue or submit a pull request!

1. Add a new function to core/src/Assertions
2. Add tests for both the positive and negative cases in core/tests/Assertions
3. Add a field for the assertion to core/src/Assertions/index.ts