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

• Node.js 14, 16, 18, 20

  (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)
  • 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 Q4 2023) will support:

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

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

npm install --dev xunit.ts

or

yarn add --dev xunit.ts

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.

MyTestSuite.ts:

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

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

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"
	}
}

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.

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.

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.

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

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

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