Comment Directives

The comment directives are single-line comments that serve as inline configuration for the test runner.

Usage

A directive must be a single-line comment starting with the @tstyche namespace followed by the directive keyword. Some directives require an argument. A note may follow after two or more hyphens.


// @tstyche if { target: ">=5.7" } -- Only when TypeScript 5.7 or above is used

The argument text is parsed as a JSON string, but unquoted keys, single quotes and trailing commas are allowed. This means you can style the arguments like the rest of the code.

Directives

The scope of a directive can be:

the whole test file (place it at the top of the file)
a single assertion or a test helper (place it above any expect(), test() or describe())
or both of the above

When placed in the wrong scope, a comment directive holds no special meaning.

`// @tstyche fixme`

Scope: a single assertion or a test helper

Marks an expect(), test() or describe() as failing.


import { ,  } from "tstyche";
 
declare function (: () => unknown): void;
declare function (: () => <unknown>): <void>;
 
((() => {}))..<void>();
// @tstyche fixme -- This should work, see: #265
((() => .()))..<<void>>();
 
("() => unknown", () => {
  ((() => {}))..<void>();
});
 
// @tstyche fixme -- Known bug, see: #345
("() => Promise<unknown>", () => {
  ((() => .()))..<<void>>();
});

The runner behaves as follows:

when an expect() is marked, verify that it actually fails
when a test() or describe() is marked, verify that it has at least one failing child

`// @tstyche if`

Scope: a single assertion or a test helper, or the whole test file
Argument type: { target: string }

Marks an expect(), test() or describe() to run only when the specified condition matches.


import { ,  } from "tstyche";
 
function (: unknown):  is  {
  return  instanceof ;
}
 
("isUint8Array", () => {
  const : <unknown> = [];
 
  // @tstyche if { target: ">=5.7" } -- Before TypeScript 5.7, 'Uint8Array' was not generic
  (.())..<<<>>>();
 
  // @tstyche if { target: "<5.7" }
  (.())..<<>>();
});

Placing this directive at the top of the file applies the condition to the whole file.

`// @tstyche template`

Scope: the whole test file

Marks a test file as a template. When the directive is found, the default export is interpreted as type test text.

For example, the following:


// @tstyche template -- For documentation, see: https://tstyche.org/guides/template-test-files
 
let  = `import { expect, test } from "tstyche";
`;
 
for (const  of ["string", "number"]) {
   += `test("is ${} a string?", () => {
  expect<${}>().type.toBe<string>();
});
`;
}
 
export default ;

is interpreted as:


import { ,  } from "tstyche";
("is string a string?", () => {
  <string>()..<string>();
});
("is number a string?", () => {
  <number>()..<string>();
});

To learn more, see the Template Test Files page.