Unit Tests

Unit Tests -- Files and Locations, Patterns

This document describes the naming and location of test files as discussed in our Keyman conference in November 2024. It describes what we aim for in the long-term and isn't completely reflected in our current repo yet.

Filenames

In order to be able to find tests across our different platforms we use the same file naming pattern across all platforms: Files containing unit (or other) tests should be named <filename>.tests.<ext>, e.g. tests for foo.ts would go into foo.tests.ts.

(Since unit test files usually contain more than one test we use the plural tests instead of the singular)

File Locations

Folder/Test file	Description
<product>/src/foo.cpp	Source code for the product
<product>/tests/foo.tests.cpp	Automated tests for unit foo.cpp (some places still use <product>/src/tests/)
<product>/tests/manual/loading.tests.cpp	Other kinds of tests like manual tests, integration tests etc can go in a sub-folder of <product>/tests. The sub-folder should get a descriptive name that shows what kind of tests it contains

Patterns

C/C++

For our homegrown C/C++ tests, do not use assert(); instead use test_assert.h and test_assert() and friends. (Or convert to GoogleTest, which is better). For more information, see discussion.

Typescript

To unit test ESModules, we need to expose private or module-local functions without exporting them for use directly by other modules. We do this by exporting unitTestEndpoints, which can then be imported and used in a unit test, for example:

/**
 * @internal
 * these are exported only for unit tests, do not use
 */
export const unitTestEndpoints = {
  checkMessageOverride,
  commandOptionsMessageToCompilerOptionsMessage
};

Classes can have static and instance functions. The pattern is similar; don't forget to bind to this for instance functions:

  private async getCloudSourceProject(source: string): Promise<GitHubRef> {
    ...
  }

  /** @internal */
  public unitTestEndPoints = {
    getCloudSourceProject: this.getCloudSourceProject.bind(this),
  };

Links

• discussion doc