metamatcher v1.0.48
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.
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago