Skip to content

Commit c9c4462

Browse files
boblatboblat
committed
feat: add docs for setting up jest with algorand-typescript-testing
1 parent a8e4d74 commit c9c4462

File tree

9 files changed

+267
-3
lines changed

9 files changed

+267
-3
lines changed

‎README.md‎

Lines changed: 79 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,14 @@ npm i @algorandfoundation/algorand-typescript-testing
4242

4343
Let's write a simple contract and test it using the `algorand-typescript-testing` framework.
4444

45+
#### Configuring vitest
46+
4547
If you are using [vitest](https://vitest.dev/) with [@rollup/plugin-typescript](https://www.npmjs.com/package/@rollup/plugin-typescript) plugin, configure `puyaTsTransformer` as a `before` stage transformer of `typescript` plugin in `vitest.config.mts` file.
4648

4749
```typescript
4850
import typescript from '@rollup/plugin-typescript'
4951
import { defineConfig } from 'vitest/config'
50-
import { puyaTsTransformer } from '@algorandfoundation/algorand-typescript-testing/test-transformer'
52+
import { puyaTsTransformer } from '@algorandfoundation/algorand-typescript-testing/vitest-transformer'
5153

5254
export default defineConfig({
5355
esbuild: {},
@@ -56,7 +58,6 @@ export default defineConfig({
5658
},
5759
plugins: [
5860
typescript({
59-
tsconfig: './tsconfig.json',
6061
transformers: {
6162
before: [puyaTsTransformer],
6263
},
@@ -76,6 +77,82 @@ beforeAll(() => {
7677
})
7778
```
7879

80+
#### Configuring jest
81+
82+
If you are using [jest](https://jestjs.io/) with [ts-jest](https://www.npmjs.com/package/ts-jest), [@jest/globals](https://www.npmjs.com/package/@jest/globals) and [ts-node](https://www.npmjs.com/package/ts-node) plugins, configure `puyaTsTransformer` as a `before` stage transformer of `typescript` plugin in `jest.config.ts` file.
83+
84+
```typescript
85+
import { createDefaultEsmPreset, type JestConfigWithTsJest } from 'ts-jest'
86+
87+
const presetConfig = createDefaultEsmPreset({})
88+
const jestConfig: JestConfigWithTsJest = {
89+
...presetConfig,
90+
testMatch: ['**/*.test.ts'],
91+
setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
92+
transform: {
93+
'^.+\\.tsx?$': [
94+
'ts-jest',
95+
{
96+
useESM: true,
97+
astTransformers: {
98+
before: ['node_modules/@algorandfoundation/algorand-typescript-testing/test-transformer/jest-transformer.mjs'],
99+
},
100+
},
101+
],
102+
},
103+
extensionsToTreatAsEsm: ['.ts'],
104+
}
105+
export default jestConfig
106+
```
107+
108+
`algorand-typescript-testing` package also exposes additional equality testers which enables the smart contract developers to write terser test by avoiding type casting in assertions. It can setup in `beforeAll` hook point in the setup file, `jest.setup.ts`.
109+
110+
```typescript
111+
import { beforeAll, expect } from '@jest/globals'
112+
import { addEqualityTesters } from '@algorandfoundation/algorand-typescript-testing'
113+
114+
beforeAll(() => {
115+
addEqualityTesters({ expect })
116+
})
117+
```
118+
119+
It is also handy to add in a script to run `jest` with `--experimental-vm-modules` flag in `package.json`.
120+
121+
```json
122+
{
123+
"name": "puya-ts-demo",
124+
"scripts": {
125+
"test:jest": "tsc && node --experimental-vm-modules node_modules/jest/bin/jest"
126+
}
127+
}
128+
```
129+
130+
There is also a patch file `ts-jest+29.2.5.patch` that needs to be applied to `ts-jest` package to for the `puyaTsTransformer` to work with the test files.
131+
132+
1. Place the file in `<rootDir>\patches` folder.
133+
1. Install [patch-package](https://www.npmjs.com/package/patch-package) package as a dev dependency.
134+
1. Add `"postinstall": "patch-package",` script in `package.json` file.
135+
The patch will then be applied with every `npm install` call.
136+
137+
```patch
138+
diff --git a/node_modules/ts-jest/dist/legacy/compiler/ts-compiler.js b/node_modules/ts-jest/dist/legacy/compiler/ts-compiler.js
139+
index 5198f8f..addb47c 100644
140+
--- a/node_modules/ts-jest/dist/legacy/compiler/ts-compiler.js
141+
+++ b/node_modules/ts-jest/dist/legacy/compiler/ts-compiler.js
142+
@@ -234,7 +234,7 @@ var TsCompiler = /** @class */ (function () {
143+
var _a;
144+
// Initialize memory cache for typescript compiler
145+
this._parsedTsConfig.fileNames
146+
- .filter(function (fileName) { return constants_1.TS_TSX_REGEX.test(fileName) && !_this.configSet.isTestFile(fileName); })
147+
+ .filter(function (fileName) { return constants_1.TS_TSX_REGEX.test(fileName); })
148+
// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
149+
.forEach(function (fileName) { return _this._fileVersionCache.set(fileName, 0); });
150+
/* istanbul ignore next */
151+
152+
```
153+
154+
After the setup, the examples provided using `vitest` can be converted to work with `jest` by simply swapping the `import {...} from 'vitest'` with `import {...} from '@jest/globals'`.
155+
79156
#### Contract Definition
80157

81158
```typescript

‎docs/code/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
- [subcontexts/contract-context](subcontexts/contract-context/README.md)
1111
- [subcontexts/ledger-context](subcontexts/ledger-context/README.md)
1212
- [subcontexts/transaction-context](subcontexts/transaction-context/README.md)
13+
- [test-transformer/jest-transformer](test-transformer/jest-transformer/README.md)
14+
- [test-transformer/vitest-transformer](test-transformer/vitest-transformer/README.md)
1315
- [value-generators](value-generators/README.md)
1416
- [value-generators/arc4](value-generators/arc4/README.md)
1517
- [value-generators/avm](value-generators/avm/README.md)

‎docs/code/test-transformer/jest-transformer/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[**@algorandfoundation/algorand-typescript-testing**](../../README.md)
2+
3+
***
4+
5+
[@algorandfoundation/algorand-typescript-testing](../../README.md) / test-transformer/jest-transformer
6+
7+
# test-transformer/jest-transformer
8+
9+
## Variables
10+
11+
- [name](variables/name.md)
12+
- [version](variables/version.md)
13+
14+
## Functions
15+
16+
- [factory](functions/factory.md)

‎docs/code/test-transformer/jest-transformer/functions/factory.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
[**@algorandfoundation/algorand-typescript-testing**](../../../README.md)
2+
3+
***
4+
5+
[@algorandfoundation/algorand-typescript-testing](../../../README.md) / [test-transformer/jest-transformer](../README.md) / factory
6+
7+
# Function: factory()
8+
9+
> **factory**(`compilerInstance`): `TransformerFactory`\<`SourceFile`\>
10+
11+
Defined in: [src/test-transformer/jest-transformer.ts:49](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/test-transformer/jest-transformer.ts#L49)
12+
13+
Factory function that creates TypeScript program transformers for Jest.
14+
Used by ts-jest to transform TypeScript files during test execution.
15+
Initialized with default transformer configuration.
16+
17+
## Parameters
18+
19+
### compilerInstance
20+
21+
#### program
22+
23+
`Program`
24+
25+
## Returns
26+
27+
`TransformerFactory`\<`SourceFile`\>
28+
29+
## Example
30+
31+
```ts
32+
// Use as before stage transformer with custom config in jest.config.ts
33+
import { createDefaultEsmPreset, type JestConfigWithTsJest } from 'ts-jest'
34+
35+
const presetConfig = createDefaultEsmPreset({})
36+
const jestConfig: JestConfigWithTsJest = {
37+
...presetConfig,
38+
transform: {
39+
'^.+\\.tsx?$': [
40+
'ts-jest',
41+
{
42+
useESM: true,
43+
astTransformers: {
44+
before: ['node_modules/@algorandfoundation/algorand-typescript-testing/test-transformer/jest-transformer.mjs'],
45+
},
46+
},
47+
],
48+
},
49+
extensionsToTreatAsEsm: ['.ts'],
50+
}
51+
export default jestConfig
52+
```

‎docs/code/test-transformer/jest-transformer/variables/name.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[**@algorandfoundation/algorand-typescript-testing**](../../../README.md)
2+
3+
***
4+
5+
[@algorandfoundation/algorand-typescript-testing](../../../README.md) / [test-transformer/jest-transformer](../README.md) / name
6+
7+
# Variable: name
8+
9+
> `const` **name**: `"puyaTsTransformer"` = `'puyaTsTransformer'`
10+
11+
Defined in: [src/test-transformer/jest-transformer.ts:15](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/test-transformer/jest-transformer.ts#L15)

‎docs/code/test-transformer/jest-transformer/variables/version.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[**@algorandfoundation/algorand-typescript-testing**](../../../README.md)
2+
3+
***
4+
5+
[@algorandfoundation/algorand-typescript-testing](../../../README.md) / [test-transformer/jest-transformer](../README.md) / version
6+
7+
# Variable: version
8+
9+
> `const` **version**: `"0.1.0"` = `'0.1.0'`
10+
11+
Defined in: [src/test-transformer/jest-transformer.ts:16](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/test-transformer/jest-transformer.ts#L16)

‎docs/code/test-transformer/vitest-transformer/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[**@algorandfoundation/algorand-typescript-testing**](../../README.md)
2+
3+
***
4+
5+
[@algorandfoundation/algorand-typescript-testing](../../README.md) / test-transformer/vitest-transformer
6+
7+
# test-transformer/vitest-transformer
8+
9+
## Functions
10+
11+
- [puyaTsTransformer](functions/puyaTsTransformer.md)

‎docs/code/test-transformer/vitest-transformer/functions/puyaTsTransformer.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
[**@algorandfoundation/algorand-typescript-testing**](../../../README.md)
2+
3+
***
4+
5+
[@algorandfoundation/algorand-typescript-testing](../../../README.md) / [test-transformer/vitest-transformer](../README.md) / puyaTsTransformer
6+
7+
# Function: puyaTsTransformer()
8+
9+
TypeScript transformer for Algorand TypeScript smart contracts and testing files
10+
which is mainly responsilbe for swapping in stub implementations of op codes,
11+
and capturing TypeScript type information for the Node.js runtime.
12+
13+
*
14+
15+
## Param
16+
17+
Configuration options
18+
19+
## Param
20+
21+
File extensions to process
22+
23+
## Param
24+
25+
Package name for testing imports
26+
27+
## Example
28+
29+
```ts
30+
// Use as before stage transformer with custom config in vitest.config.mts
31+
import typescript from '@rollup/plugin-typescript'
32+
import { defineConfig } from 'vitest/config'
33+
import { puyaTsTransformer } from '@algorandfoundation/algorand-typescript-testing/vitest-transformer'
34+
35+
export default defineConfig({
36+
esbuild: {},
37+
plugins: [
38+
typescript({
39+
tsconfig: './tsconfig.json',
40+
transformers: {
41+
before: [puyaTsTransformer],
42+
},
43+
}),
44+
],
45+
})
46+
```
47+
48+
## Call Signature
49+
50+
> **puyaTsTransformer**(`context`): `Transformer`\<`SourceFile`\>
51+
52+
Defined in: [src/test-transformer/vitest-transformer.ts:54](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/test-transformer/vitest-transformer.ts#L54)
53+
54+
### Parameters
55+
56+
#### context
57+
58+
`TransformationContext`
59+
60+
### Returns
61+
62+
`Transformer`\<`SourceFile`\>
63+
64+
## Call Signature
65+
66+
> **puyaTsTransformer**(`config`): `TransformerFactory`\<`SourceFile`\>
67+
68+
Defined in: [src/test-transformer/vitest-transformer.ts:55](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/test-transformer/vitest-transformer.ts#L55)
69+
70+
### Parameters
71+
72+
#### config
73+
74+
`Partial`\<`TransformerConfig`\>
75+
76+
### Returns
77+
78+
`TransformerFactory`\<`SourceFile`\>

‎typedoc.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
{
22
"$schema": "https://typedoc.org/schema.json",
3-
"entryPoints": ["./src/index.ts", "./src/value-generators/*.ts", "./src/subcontexts/*.ts"],
3+
"entryPoints": [
4+
"./src/index.ts",
5+
"./src/value-generators/*.ts",
6+
"./src/subcontexts/*.ts",
7+
"./src/test-transformer/jest-transformer.ts",
8+
"./src/test-transformer/vitest-transformer.ts"
9+
],
410
"exclude": ["types/*.spec.ts"],
511
"entryPointStrategy": "expand",
612
"out": "docs/code",

0 commit comments

Comments
 (0)