Matcher for Jest/Vitest TypeScript checking code properties (via TypeScript)
!logo metamatcher
===============================
Matchers for Jest checking TypeScript code properties via TypeScript
and other matchers useful for using tests as a grading tool.
Install with npm:
``
npm install --save-dev metamatcher
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:
`javascript`
"jest": {
"setupFilesAfterEnv": ["metamatcher/setup"]
}
or the following one in your jest.config.js:javascript`
setupFilesAfterEnv: ["metamatcher/setup"]
does not work... what did I miss?
You need to initially load the program somehow. It is recommended to do this in the beforeAll function:
`javascript`
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();
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[]
The following matchers for syntax and convention checks are provided:
- toBeAsync for function
- toBeDirectRecursive for function
- toBeRecursive for function
- toCallFunction for function or whole source file
- toUseArrays for function or whole source file
- toUseAwait for function (nested functions as skipped)
- toUseLoop for function
- toUseRegExp for function
- toContainStringLiteral for function or whole source file
- toContainNumericLiteral for function or whole source file
- toBeType for types, these are declared types!
- toBeBaseType for types, these are declared types!
- toDeclareMember
All these function take an optional argument with a message to be displayed in case of failure.
`
expect(functionDeclaration("tests/samples.ts", "funcWithRecursion")).toBeRecursive();
- 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.
- toBeFileAndExist
- toBeFolderAndExist
The following matchers are provided for use with custom messages:
- toBe…WithMessage: Similar to toBe…, but with an optional parameter
which may be either a string (with a message) or a function producing an message.
Additionally, function
- creates a message if the call to the function fails.
The emitted messages are enclosed in §§§ by default. This allows for tools processing the test output to extract the messages.METAMATCHER_MSG_PREFIX
The enclosing tags can be changed via and METAMATCHER_MSG_POSTFIX environment variables.
Example:
`javascriptExpected ${rec} to be ${exp}
expect(1).toBeWithMessage(2, (rec,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
`javascript`
await expect(asyncCall()).rejects.toThrowWithMessage("message");
will not work. Instead, use
`javascript`
try {
await asyncCall();
throw new Error("My message");
} catch (e) {
// expected
}
in this special case.
If you want to add special messages, in particular for tools analyzing the output later on in your tool chain, you may want to use runWithFailMessage (or short rwfm).
This function encappsulates a call and replaces or modifies the thrown error message.
`javascript`
runWithFailMessage(()=>someFoo(), "Folgefehler");
This will emit if someFoo() would throw an error.
You can also use a function to generate the message, e.g.
`javascript`
runWithFailMessage(()=>someFoo(), (errMsg) => "Folgefehler: " + errMsg);
This works also with async code:
`typescript
async function bar(): Promise
const s: string = await rwfm(()=>bar(), (errMsg) => Folgefehler: ${errMsg});``
In order to test command line interfaces (CLIs), some utility functions are provided:
- findBin: find the bin file defined in a package.json
- callCLI: calls a cli tool and captures output
- callNodeBin: calls a node cli tool and captures output
- 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
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.
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.