metamatcher

Matchers for Jest checking TypeScript code properties via TypeScript and other matchers useful for using tests as a grading tool.

Install

Install with npm:

npm install --save-dev metamatcher

Setup

You need to somehow run the metamatcher module in order to extend expect at runtime. This can be done by either importing the module in your tests (which you will do in order to use locator functions).

Adding the following line to your package config:

"jest": {
  "setupFilesAfterEnv": ["metamatcher/setup"]
}

or the following one in your jest.config.js:

  setupFilesAfterEnv: ["metamatcher/setup"]

does not work... what did I miss?

Usage

You need to initially load the program somehow. It is recommended to do this in the beforeAll function:

beforeAll(()=>{ loadProgram("src/file.ts") });

In a test you can then use queries for declarations and matchers, e.g.

expect(functionDeclaration("src/someFile.ts", "foo")).toBeRecursive();

Locators

The following locators, i.e. functions returning AST elements or other information, are provided:

• sourceFile(filename: string): ts.SourceFile
• functionDeclaration(sourceFileName: string, functionName: string): ts.FunctionDeclaration
• functionDef(sourceFileName: string, functionName: string): ts.SignatureDeclaration
• returnType(fileName, declName): string
• varDecl(sourceFileName: string, varName: string): ts.VariableDeclaration
  • typeName(varDecl: ts.VariableDeclaration, convertToBaseType = true): string
• allImportModuleSpecifier(sourceFileName: string): string[]
• allExportedNames(sourceFileName: string): string[]
• assignments(func: ts.SignatureDeclaration, lhsString: string): ts.Expression[]

Code Matchers

The following matchers for syntax and convention checks are provided:

• toBeRecursive for function
• toBeDirectRecursive for function
• toUseArrays for function or whole source file
• toUseLoop for function
• toUseFunction for function or whole source file
• toBeAsync for function
• toUseAwait for function (nested functions as skipped)
• toContainStringLiteral for function or whole source file
• toContainLiteral for function or whole source file

All these function take an optional argument with a message to be displayed in case of failure.

expect(functionDeclaration("tests/samples.ts", "funcWithRecursion")).toBeRecursive();

Additional Meta-Functions

• collectJestTests: returns all Jests tests of a given module (by mocking test with a collector function and importing the module), even works with each and describe! Note that the module is actually executed (dynamic import, almost as dangerous as eval!). The module is to be specified from the project root folder.

Matcher and beforeAll/beforeEach with custom messages

The following matchers are provided for use with custom messages:

• toBeWithMessage: Similar to toBe, but with an optional parameter which may be either a string (with a message) or a function producing an message surrounded in "§§§" (to be processed by other tools later on).
  • and more like that: toBeEqualWithMessage, toBeGreater(OrEqual)WithMessage, toBeLess(OrEqual)WithMessage

Example:

expect(1).toBeWithMessage(2, (rec,exp) => `Expected ${rec} to be ${exp}`);

This will output a line like this:

§§§Expected 1 to be 2§§§

This allows other tools to extract exactly this message from the test output.

This differs from the solution for custom messages provided by (https://github.com/mattphillips/jest-expect-message)[jest-expect-message]: jest-expect-message can only print out (more or less) constant messages, but the message cannot contain the actual values of the test. This is not sufficient for grading purposes.

Note that toThrow does not work in the async case, since if the promise is rejected, the matcher is not called at all. That is

await expect(asyncCall()).rejects.toThrowWithMessage("message");

will not work. Instead, use

try {
  await asyncCall();
  throw new Error("My message");
} catch (e) {
  // expected
}

in this special case.

Development

• Using the TypeScript compiler API: https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API#using-the-type-checker
• https://ts-ast-viewer.com/ (for AST)
• https://stackoverflow.com/questions/tagged/typescript-compiler-api?sort=Newest&edited=true

Status

This library is developed on demand. It is not a fully-features code testing library but only contains matchers as far as needed by the author. It is basically made public in order to simplify the author's scripts.

License

This program and the accompanying materials are made available under the terms of the Eclipse Public License v. 2.0 which is available at https://www.eclipse.org/legal/epl-2.0.