Skip to content

Commit

Permalink
Merge pull request #335 from ton-community/test_docs_improvements
Browse files Browse the repository at this point in the history 
Test docs improvements
  • Loading branch information
@reveloper
reveloper committed Aug 25, 2023
2 parents 4b1be4e + 254cce7 commit 69ea3b7
Show file tree
Hide file tree
Showing 3 changed files with 35 additions and 44 deletions.
2 changes: 1 addition & 1 deletion docs/develop/func/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Here is a simple example method for sending money written in FunC:
var msg = begin_cell()
.store_uint(0x10, 6) ;; nobounce
.store_slice(address)
.store_grams(amount)
.store_coins(amount)
.end_cell();
send_raw_message(msg, 64);
Expand Down
17 changes: 0 additions & 17 deletions docs/develop/smart-contracts/examples.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,23 +132,6 @@ Make sure you have thoroughly tested contracts before using them in a production
* [wallet.fif](https://github.com/ton-blockchain/ton/blob/master/crypto/smartcont/wallet.fif)
* [wallet-v3-code.fif](https://github.com/ton-blockchain/ton/blob/master/crypto/smartcont/wallet-v3-code.fif)

## Examples of Tests for Smart Contracts

* [liquid-staking-contract sandbox tests](https://github.com/ton-blockchain/liquid-staking-contract/tree/main/tests)
* [governance_tests](https://github.com/Trinketer22/governance_tests/blob/master/config_tests/tests/)
* [JettonWallet.spec.ts](https://github.com/EmelyanenkoK/modern_jetton/blob/master/tests/JettonWallet.spec.ts)
* [governance_tests](https://github.com/Trinketer22/governance_tests/blob/master/elector_tests/tests/complaint-test.fc)
* [MassSender.spec.ts](https://github.com/Gusarich/ton-mass-sender/blob/main/tests/MassSender.spec.ts)
* [TonForwarder.spec.ts](https://github.com/TrueCarry/ton-contract-forwarder/blob/main/src/contracts/ton-forwarder/TonForwarder.spec.ts)
* [ton-tvm-bus](https://github.com/ton-defi-org/ton-tvm-bus)
* [wTON-contract tests](https://github.com/ton-community/wton-contract/tree/main/tests)
* [getgems tests](https://github.com/ton-community/nft-sdk/tree/main/sandbox-examples/getgems)
* [Distributor.spec.ts](https://github.com/ton-community/simple-distributor/blob/main/tests/Distributor.spec.ts)
* [Migration.spec.ts](https://github.com/Gusarich/jetton-migration/blob/main/tests/Migration.spec.ts)
* [SubdomainManager.spec.ts](https://github.com/Gusarich/simple-subdomain/blob/main/tests/SubdomainManager.spec.ts)
* [Token.spec.ts](https://github.com/Gusarich/ton-single-token/blob/main/tests/Token.spec.ts)
* [Scheduler.spec.ts](https://github.com/Gusarich/external-scheduler/blob/master/tests/Scheduler.spec.ts)

## FunC Libraries and Helpers

* https://github.com/ton-blockchain/ton/blob/master/crypto/smartcont/stdlib.fc
Expand Down
60 changes: 34 additions & 26 deletions docs/develop/smart-contracts/testing/overview.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,42 @@
# Writing Tests with Blueprint

## Testing Overview
## Overview

Testing toolkit (usually, sandbox) already included to the TypeScript SDK named Blueprint. You can create demo project and launch default test with two steps:
Test toolkit (usually, sandbox) already included to the TypeScript SDK named [Blueprint](/develop/smart-contracts/sdk/javascript). You can create demo project and launch default test with two steps:

1. Install Blueprint project
1. Create a new Blueprint project:
```bash
npm create ton@latest
npm create ton@latest MyProject
```

2. Install Blueprint project
2. Run a test:
```bash
cd MyProject
npx blueprint test
```

As a result you'll see corresponding output in the terminal window:

```bash
% npx blueprint test

> MyProject@0.0.1 test
> jest

PASS tests/Main.spec.ts
Main
✓ should deploy (127 ms)

Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 1.224 s, estimated 2 s
Ran all test suites.
```

## Basic Usage
Testing of smart contracts allows for the coverage of security, optimization of gas spending, and examination of edge cases.
Writing tests in Blueprint (that based on Sandbox) works through defining arbitary actions with the contract and comparing their results with the expected result, for example:
Writing tests in Blueprint (that based on [Sandbox](https://github.com/ton-org/sandbox)) works through defining arbitary actions with the contract and comparing their results with the expected result, for example:

```typescript
it('should execute with success', async () => { // description of the test case
Expand All @@ -32,7 +52,7 @@ it('should execute with success', async () => { //
```


### Writing Tests for Different Properties
### Writing Tests for Complex Assertion

The basic workflow of creating a test is:
1. Create a specific wrapped `Contract` entity using `blockchain.openContract()`.
Expand All @@ -44,40 +64,27 @@ The `toHaveTransaction` matcher expects an object with any combination of fields
| Name | Type | Description |
|----------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| from | Address? | Contract address of the message sender |
| to | Address | Contract address of the message destination |
| on | Address | Contract address of the message destination (Alternative name of the property `to`). |
| value | bigint? | Amount of Toncoins in the message in nanotons |
| body | Cell | Message body defined as a Cell |
| inMessageBounced | boolean? | Boolean flag Bounced. True - message is bounced, False - message is not bounced. |
| inMessageBounceable | boolean? | Boolean flag Bounceable. True - message can be bounced, False - message can not be bounced. |
| op | number? | Op code is the operation identifier number (crc32 from TL-B usually). Expected in the first 32 bits of a message body. |
| initData | Cell? | InitData Cell. Used for contract deployment processes. |
| initCode | Cell? | initCode Cell. Used for contract deployment processes. |
| deploy | boolean | Custom Sandbox flag that indicates whether the contract was deployed during this transaction. True if contract before this transaction was not initialized and after this transaction became initialized. Otherwise - False. |
| lt | bigint | Logical time (set by validators in a normal network, monotonically increases by a set interval in Sandbox). Used for defining order of transactions related to a certain contract |
| now | bigint | Unix timestamp of the transaction |
| outMessagesCount | number | Quantity of outbound messages in a certain transaction |
| oldStatus | AccountStatus | AccountStatus before transaction execution |
| endStatus | AccountStatus | AccountStatus after transaction execution |
| totalFees | bigint? | Number of spent fees in nanotons |
|aborted| boolean? | True - execution of certain transaction aborted and rollbacked because of errors or insufficient gas. Otherwise - False. |
|destroyed| boolean? | True - if the existing contract was destroyed due to executing a certain transaction. Otherwise - False. |
|exitCode| number? | TVM exit code (from compute phase) |
|actionResultCode| number? | Action phase result code |
|success| boolean? | Custom Sandbox flag that defines the resulting status of a certain transaction. True - if both the compute and the action phase succeeded. Otherwise - False. |


You can omit those that you're not interested in, and you can also pass in functions accepting those types returning booleans (`true` meaning good) to check for example number ranges, message opcodes, etc. Note however that if a field is optional (like `from?: Address`), then the function needs to accept the optional type, too.

:::tip
Learn the whole list of matcher fields from the [Sandbox documentation](https://github.com/ton-org/sandbox#test-a-transaction-with-matcher).
:::

## Tutorials

Learn more about testing from most valuable community tutorials on TON:

* [Lesson 2: Testing FunC for a Smart Contract](https://github.com/romanovichim/TonFunClessons_Eng/blob/main/lessons/smartcontract/2lesson/secondlesson.md)
* [TON Hello World part 4: Step by step guide for testing your first smart contract](https://ton-community.github.io/tutorials/04-testing/)
* [TON Smart Contract Pipeline](https://dev.to/roma_i_m/ton-smart-contract-pipeline-write-simple-contract-and-compile-it-4pnh)
* [[YouTube]Sixth lesson FunC & Blueprint. Gas, fees, tests.](https://youtu.be/3XIpKZ6wNcg)


## Examples

Check test suites used for TON Ecosystem contracts and learn by examples.
Expand All @@ -91,4 +98,5 @@ Check test suites used for TON Ecosystem contracts and learn by examples.


## See Also
* [Using Blueprint](/develop/smart-contracts/sdk/javascript)
* [Blueprint](/develop/smart-contracts/sdk/javascript)
* [toncli](/develop/smart-contracts/testing/toncli)

0 comments on commit 69ea3b7

Please sign in to comment.