Comment Directives

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

Usage

Only a single-line comment is considered to be a directive if its text starts with @tstyche namespace followed by the directive keyword. An argument must be provided if a directive requires it. Optionally, a note can be added 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 or trailing commas are allowed. This means you can style the arguments just like the rest of the code.

Directives

The scope of a directive can be:

the whole test file (use 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 a comment directive is used in the wrong scope, it holds no special meaning.

`// @tstyche fixme`

Scope: a single assertion or a test helper

Marks an expect(), test() or describe() as supposed to fail.


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 implements the following logic:

when an expect() is marked, make sure it actually fails,
when a test() or describe() is marked, check if it has a failing child.

`// @tstyche if`

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

Run an expect(), test() or describe() 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" }
  (.())..<<>>();
});

If this directive is used at the top of the file, the whole test file would run only when the specified condition matches.

`// @tstyche template`

Scope: the whole test file

Marks a test file as a template. When the directive is found, the default export of a file is interpreted as a 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.