@ton/sandbox 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.31.0] - 2025-05-20
+
+### Added
+
+- Added methods to collect metrics of contracts
+- Added `@ton/sandbox/jest-environment` and `@ton/sandbox/jest-reporter` to write metric snapshots from test run results
+- Added contract method ABI auto-mapping mechanism for detailed benchmark metrics
+- Added methods to generate delta reports from metrics of contracts
+
+## [0.30.0] - 2025-05-12
+
+### Changed
+
+- Updated config
+
 ## [0.29.0] - 2025-04-30
 
 ### Changed
@@ -377,4 +392,4 @@ type LogsVerbosity = {
 
 ### Removed
 
-- Changed `blockchain.pushMessage`, `blockchain.processQueue`, `blockchain.runQueue` to be private
+- Changed `blockchain.pushMessage`, `blockchain.processQueue`, `blockchain.runQueue` to be private

package/README.md

@@ -15,6 +15,7 @@ The key difference of this package from [ton-contract-executor](https://github.c
   * [Cross contract tests](#cross-contract-tests)
   * [Testing key points](#testing-key-points)
   * [Test examples](#test-examples)
+* [Benchmark contracts](#benchmark-contracts)
 * [Sandbox pitfalls](#sandbox-pitfalls)
 * [Viewing logs](#viewing-logs)
 * [Setting smart contract state directly](#setting-smart-contract-state-directly)
@@ -290,6 +291,109 @@ Learn more from examples:
 * [FunC Test Examples](https://docs.ton.org/develop/smart-contracts/examples#examples-of-tests-for-smart-contracts)
 * [Tact Test Examples](docs/tact-testing-examples.md) 
 
+## Benchmark contracts
+
+The `@ton/sandbox` package provides `@ton/sandbox/jest-environment` and `@ton/sandbox/jest-reporter` built-in support for benchmarking smart contract behavior during tests, including tracking gas usage, cell size, opcode execution, and action phases.
+This is especially useful for performance analysis, gas optimization, and regression checks on contract logic.
+
+> ℹ️ See also: [Collect metric API](docs/collect-metric-api.md) for low-level control and manual snapshots.
+
+### Features
+
+* Automatic metric collection from all transactions triggered during tests
+* Snapshot reporting with contract-level filters
+* Integration with [blueprint](https://github.com/ton-org/blueprint#benchmark-contracts)
+
+### Setup in `jest.config.ts`
+
+```ts
+import type { Config } from 'jest';
+
+const config: Config = {
+    preset: 'ts-jest',
+    testEnvironment: '@ton/sandbox/jest-environment',
+    globalSetup: './jest.setup.ts',
+    testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+    reporters: [
+        'default',
+        ['@ton/sandbox/jest-reporter', {
+            // options
+            snapshotDir: '.snapshot',              // output folder for benchmark reports, default: '.snapshot'
+            contractDatabase: 'contract.abi.json', // path or json a map of known contracts, see Collect metric API, default: 'contract.abi.json'
+            reportName: 'gas-report',              // report name, default: 'gas-report'
+            depthCompare: 2,                       // comparison depth, default: 2
+            removeRawResult: true,                 // remove raw metric file, default: true
+            contractExcludes: [                    // exclude specific contracts from snapshot, default: []
+                'TreasuryContract',
+            ],
+        }],
+    ],
+};
+
+export default config;
+```
+
+### How to run benchmarks
+
+To collect and save snapshot metrics:
+
+```bash
+BENCH_NEW="some" npx jest
+# or
+npx blueprint snapshot --label "some" 
+```
+
+This will:
+
+* Run your tests
+* Collect contract execution metrics
+* Save a snapshot in `.snapshot/<timestamp>.json`
+
+To compare with a previous snapshot:
+
+```bash
+BENCH_DIFF=true npx jest
+# or
+npx blueprint test --gas-report
+```
+
+### Or setup in `gas-report.config.ts`
+
+```ts
+import config from './jest.config';
+
+config.testNamePattern = '^DescribeName .* - test name$'
+config.testEnvironment = '@ton/sandbox/jest-environment'
+config.reporters = [
+    ['@ton/sandbox/jest-reporter', {
+        contractDatabase: 'abi.json',
+        contractExcludes: [
+            'TreasuryContract',
+        ],
+    }],
+]
+export default config;
+```
+
+**Collect metric and get report:**
+
+```bash
+npx blueprint snapshot --label "some label" -- --config gas-report.config.ts
+npx blueprint test --gas-report -- --config gas-report.config.ts
+```
+
+### Output structure
+
+By default, the reporter generates:
+
+```
+.project-root/
+├── .snapshot/
+│   └── 4200000000000.json    // timestamped snapshot file
+├── .sandbox-metric-raw.jsonl // raw metric log (auto-deleted by default)
+├── contract.abi.json         // map of known contracts, see Collect metric API
+└── gas-report.json           // aggregate report in json format
+```
 
 ## Sandbox pitfalls
 

package/dist/blockchain/Blockchain.js

@@ -13,6 +13,7 @@ const AsyncLock_1 = require("../utils/AsyncLock");
 const message_1 = require("../utils/message");
 const slimConfig_1 = require("../config/slimConfig");
 const testTreasurySubwalletId_1 = require("../utils/testTreasurySubwalletId");
+const collectMetric_1 = require("../metric/collectMetric");
 const CREATE_WALLETS_PREFIX = 'CREATE_WALLETS';
 function createWalletsSeed(idx) {
     return `${CREATE_WALLETS_PREFIX}${idx}`;
@@ -452,25 +453,25 @@ class Blockchain {
                 }
                 const value = target[prop];
                 if (typeof prop === 'string' && typeof value === 'function') {
+                    const ctx = {
+                        contract,
+                        methodName: prop,
+                    };
                     if (prop.startsWith('get')) {
                         return (...args) => value.apply(target, [provider, ...args]);
                     }
                     else if (prop.startsWith('send')) {
                         return async (...args) => {
-                            const ret = value.apply(target, [provider, ...args]);
+                            let ret = value.apply(target, [provider, ...args]);
                             if (ret instanceof Promise) {
-                                const r = await ret;
-                                return {
-                                    ...await blkch.runQueue(),
-                                    result: r,
-                                };
-                            }
-                            else {
-                                return {
-                                    ...await blkch.runQueue(),
-                                    result: ret,
-                                };
+                                ret = await ret;
                             }
+                            const out = {
+                                ...await blkch.runQueue(),
+                                result: ret,
+                            };
+                            await (0, collectMetric_1.collectMetric)(blkch, ctx, out);
+                            return out;
                         };
                     }
                 }