@kstasi/jest-tolk NPM

Jest Runner for Tolk

A Jest runner that enables you to write and execute unit tests for Tolk code using familiar testing patterns.

Example

Consider a simple Tolk function in sum.tolk:

fun calculateSum(a: int, b: int) {
    return a + b;
}

You can write unit tests for this function using Tolk:

import "sum.tolk"

// @scope sum()
get test_returns_sum_of_numbers() {
    val a: int = 4;
    val b: int = 7;

    assert(calculateSum(a, b) == a + b) throw 100;
}

// @scope sum()
// @exitCode 7 (type check error)
get test_fails_if_value_is_not_int() {
    val a: int = null;
    val b: int = 7;

    calculateSum(a, b);
}

Test result:

Installation

Install @tonkite/jest-tolk:
```
pnpm add -D @tonkite/jest-tolk
```

Add runner configuration to jest.config.ts:

import type { Config } from 'jest';

const config: Config = {
  projects: [
    {
      displayName: 'test',
      preset: 'ts-jest',
      testEnvironment: 'node',
      testPathIgnorePatterns: ['/node_modules/', '/dist/'],
    },
    {
      displayName: 'tolk',
      moduleFileExtensions: ['tolk'],
      testMatch: ['**/*[._]test.tolk'],
      runner: '@tonkite/jest-tolk',
    },
  ],
};

export default config;

Annotations

The runner allows you to configure the behavior of tests using special annotations in comments.

Example:

/**
 * @test
 * @scope examples
 * @exitCode 500
 */
get should_fail_with_exit_code_500() {
    throw 500;
}

Supported Annotations:

Annotation	Example	Description
`@exitCode [exitCode]`	`// @exitCode 500`	Specifies the expected exit code. Default: `0`.
`@scope [scope]`	`// @scope Pool::onSwap`	Specifies the scope of a test (useful for test grouping).
`@skip`	`// @skip`	Marks a test to be skipped.
`@todo`	`// @todo`	Marks a test to be done later.
`@test`	`// @test`	Marks a get-method (which isn't prefixed by `test_`) as a test.
`@balance [balance]`	`// @balance 1000000000`	Sets a balance for a test. Default: `1000000000` (1 TON).
`@gasLimit [gas limit]`	`// @gasLimit 50000`	Sets a gas limit for a test. Default: `10000`.
`@unixTime [unix time]`	`// @unixTime 1735231203`	Sets a Unix time for a test. Default: current time.
`@no-main`	`// @no-main`	Disables adding an entrypoint `fun main() {}` to avoid collision with an existing one.
`@fuzz [tlb]`	`// @fuzz _ a:# = Args;`	Marks a test as a fuzz test with optional TLB for test arguments.
`@runs [runs]`	`// @runs 100`	Sets a number of runs for a fuzz test. Default: `10`.

Fuzz Testing

Fuzz testing injects random, edge-case, or fixture-based data into tests to uncover bugs and vulnerabilities.

Fuzz Testing in Tolk

Fuzz is supported through annotation @fuzz, optionally with a TLB schema for Args type.

// @fuzz
// @runs 10
get test_fuzz_sum_of_numbers(a: int, b: int) s{
    assert(calculateSum(a, b) == a + b) throw 101;
}

// @fuzz _ a: uint8 b:# = Args;
get test_fuzz_with_tlb(a: int, b: int) {
    assert(calculateSum(a, b) == a + b) throw 102;
}

Fuzz Testing with Fixtures

Fixtures are predefined data sets that are declared as get-methods with prefix fixture_. If they are defined, random values are selected from them.

get fixture_x() {
    return (6, 7, 8, 9, 10);
}

get fixture_y() {
    return (1, 2, 3, 4, 5);
}

// @fuzz
get test_fuzz_sum_of_numbers_with_fixtures(x: int, y: int) {
    assert(calculateSum(x, y) == x + y) throw 101;
}

Supported Data Types

Currently, the following data types are supported:

int - Integer fuzzing. Better use with TLB.
slice - Slice fuzzing.
address - Address fuzzing.
coins - Coins fuzzing.

License

tolk jest ton

@jest/test-result @ton-community/tlb-codegen @ton-community/tlb-parser @tonkite/tree-sitter-tolk chalk create-jest-runner jest-message-util

0.0.11

11 months ago

0.0.10

11 months ago

0.0.9

11 months ago