TypeScript xUnit XML Reporter

Common errors

• 'typescript-xunit-xml' is not recognized as an internal or external command, operable program or batch file.

  cause The `typescript-xunit-xml` CLI tool is not found in the system's PATH or within `node_modules/.bin`.
  fix Install the package globally (`npm install -g typescript-xunit-xml`), or use `npx typescript-xunit-xml`, or ensure `node_modules/.bin` is in your PATH in shell scripts.

• tsc: The term 'tsc' is not recognized as the name of a cmdlet, function, script file, or operable program.

  cause The TypeScript compiler (`tsc`) is not installed globally or is not accessible in the execution environment's PATH.
  fix Install TypeScript globally (`npm install -g typescript`) or ensure `tsc` is available in your project's `node_modules/.bin` (e.g., by adding `"scripts": { "test": "tsc && ..." }` to `package.json` and running `npm test`).

• Error: Invalid TS diagnostics output. Expected format...

  cause The input provided to `typescript-xunit-xml` (via pipe or programmatic `parse` function) is not in the expected format of standard TypeScript compiler diagnostics, likely due to a `--pretty` flag or other output modifications.
  fix Ensure `tsc` is run without the `--pretty` flag and that no other tools are altering its `stdout` or `stderr` before it reaches `typescript-xunit-xml`.

Warnings

• breaking The package relies on parsing the standard output format of the TypeScript compiler (tsc). Any future breaking changes to tsc's diagnostic output format could lead to incorrect parsing or runtime errors within `typescript-xunit-xml`.
  Fix: Monitor for updates to `typescript-xunit-xml` when upgrading major TypeScript compiler versions. If issues arise, consider contributing a fix or using an alternative reporter.
• gotcha Currently, `typescript-xunit-xml` does not support parsing `--pretty` output from the TypeScript compiler. Using `--pretty` will result in malformed or incomplete XML reports.
  Fix: Ensure `tsc` is invoked without the `--pretty` flag when its output is piped to `typescript-xunit-xml`. The roadmap indicates future support, but it's not present in v1.2.0.
• gotcha When running `tsc` in environments that buffer stdout/stderr or modify output (e.g., some CI runners, IDE integrations), the raw output might be altered before reaching `typescript-xunit-xml`, leading to parsing failures.
  Fix: Ensure `tsc` output is pristine. Use direct piping (`|`) and avoid intermediate tools that might reformat text. In Node.js, capture `stderr` and `stdout` directly from `child_process` as demonstrated in the quickstart.
• gotcha TypeScript compiler warnings are typically reported by `typescript-xunit-xml` as 'skipped' tests in the xUnit report, while errors are reported as 'failures'. This distinction is important for CI systems that differentiate between these states.
  Fix: Understand how your CI system interprets xUnit 'skipped' vs. 'failed' test cases. Adjust build failure criteria in your CI pipeline if you wish warnings to cause a hard build break.

Install

• npm install typescript-xunit-xml npm
• yarn add typescript-xunit-xml yarn
• pnpm add typescript-xunit-xml pnpm

Imports

• parse
  wrong:

  import parse from 'typescript-xunit-xml';

  correct:

  import { parse } from 'typescript-xunit-xml';

  Imports the `parse` function to convert raw TypeScript compiler output strings into structured message objects. This is a named export.
• format
  wrong:

  import format from 'typescript-xunit-xml';

  correct:

  import { format } from 'typescript-xunit-xml';

  Imports the `format` function to serialize an array of message objects into a well-formed xUnit XML string. This is a named export.
• { parse, format } (CommonJS)
  wrong:

  const converter = require('typescript-xunit-xml'); // Then access converter.parse, converter.format

  correct:

  const { parse, format } = require('typescript-xunit-xml');

  CommonJS pattern to destructure both `parse` and `format` functions from the module's exports object. Directly requiring the module's main file is common for programmatic access.

Quickstart

Demonstrates programmatic usage of `typescript-xunit-xml` to process TypeScript compiler output from a dummy project and generate an xUnit XML report, simulating typical CI/CD integration.

import { readFileSync, writeFileSync } from 'fs';
import { spawnSync } from 'child_process';
import { parse, format } from 'typescript-xunit-xml'; // Programmatic API

const tsConfigFile = 'tsconfig.json';
const tsCodeFile = 'src/index.ts';

// Ensure src directory exists and create dummy files for demonstration
if (!require('fs').existsSync('src')) require('fs').mkdirSync('src');
writeFileSync(tsCodeFile, `
function greet(name: string): string {
    return \`Hello, \${name}!\`;
}
const x: number = 'hello'; // Intentionally cause a type error for the demo
console.log(greet("World"));
`);
writeFileSync(tsConfigFile, `
{
  "compilerOptions": {
    "target": "es2016", "module": "commonjs", "strict": true,
    "esModuleInterop": true, "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true, "noEmit": true
  },
  "include": ["src/**/*.ts"]
}
`);

console.log("Running tsc and piping output to typescript-xunit-xml...");
// Simulate the CLI usage: tsc --project . --noEmit | typescript-xunit-xml
// The --noEmit flag is crucial for tsc to output diagnostics to stdout/stderr instead of compiling files.
const tscProcess = spawnSync('tsc', ['--project', '.', '--noEmit'], { encoding: 'utf8' });

if (tscProcess.status !== 0) {
    console.warn("TypeScript compilation errors detected (expected for this demo).");
} else {
    console.log("No TypeScript errors. Outputting empty xUnit XML.");
}

// tsc often sends errors to stderr, so check both
const tscOutput = (tscProcess.stderr || tscProcess.stdout).toString();

// Use the programmatic API to process the output
const parsedMessages = parse(tscOutput);
const xunitXml = format(parsedMessages);

writeFileSync('junit.xml', xunitXml);
console.log("Generated junit.xml with xUnit report (check 'junit.xml' for content):");
// console.log(xunitXml); // Uncomment to see the XML directly in console

// Clean up dummy files
try {
  require('fs').unlinkSync(tsCodeFile);
  require('fs').unlinkSync(tsConfigFile);
  require('fs').rmdirSync('src');
  console.log("Cleaned up dummy files.");
} catch (e) {
  console.error("Cleanup failed:", e.message);
}