Tests in this folder are exclusively for smart contracts (under code/contracts) and some core library functions related to small contracts (under code/lib).

Tests for other components, such as the relayer, the client, and the core library, are provided at separate locations.

It is recommended that you run tests against a local Ganache instance. Please refer to the documentation at code/env/README.md.

The tests have deep logging functionality controlled by the VERBOSE flag

• VERBOSE=1 or VERBOSE=true turns on debugging logging
• VERBOSE=0 or VERBOSE=false runs in a quieter mode

To run the complete set of tests use

yarn test

To run a specific suite of tests in a file use

VERBOSE=1 truffle test test/general.js --network=dev

To run an individual test use

VERBOSE=0 truffle test --network=ganache --compile-none --grep 'AD-WALLET-1'

Before each test, some wallets are automatically deployed. They are encapsulated in a test data object. See deployTestData and init functions in util.js for more details. A breakdown of the test data object is given below.

All users are funded with HALF_ETH (half the native token) and initially have a SpendingLimit of ONE_ETH (one native token). The test users are:

• alice: primary user funded with 1000 TestERC20, 2 TestERC721 tokens with id 2 and 3, and 50 TestERC1155 tokens with 20 of token 2, and 30 of token 3.
• bob: used for testing token transfers from alice and tracking tokens
• carol: used for testing backlinks and forwarding operations involving alice
• dora: used for testing overriding backlinks
• ernie: general purpose testing user

The following token contracts are deployed using the first account available in the environment:

• testerc20: ERC20 contract (TestERC20) with 10000000 minted supply, of which 1000 tokens are given to alice.
• testerc721: ERC721 contract (TestERC721) with 10 different tokens [0,1,2,3,4,5,6,7,8,9]. Token [2,3] are given to alice.
• testerc1155: ERC1155 contract (TestERC1155) with 10 types of tokens [0,1,2,3,4,5,6,7,8,9]. They have corresponding supply of [10,20,30,40,50,66,70,80,90,100], which are minted ahead of time. Here, 50 TestERC1155 tokens with 20 of token 2 and 30 of token 3 are given to alice.

The following contracts are also deployed to provide additional helpers for tests. Note that no initial transfer were made from these contracts. The tokens and amounts minted ahead of the time are the same.

• testerc20v2 (ERC20)
• testerc721v2 (ERC721)
• testerc1155v2 (ERC1155)

Following is a summary of each testing area:

Below is an overview of writing tests for a new operation or new test area. For tests extending an existing area, please follow the code conventions and structures in the corresponding file.

First Postive Use Case

First, create a new file and write out how you expect a successful operation to play out. Please feel free to refer to examples in tokens.js and others.

• Test and Expected Result: Place this in comments at the top of the test

• Test Name: Uniquely identify the test and state what the test is for e.g. TN-BASIC-0 TRACK: must be able to track ERC20 tokens. Here the test identifier TN-BASIC-0 helps another person to run this test individually.

• Initialization and Setup: Here you create and fund your wallets and create any tokens that may be needed for the test. Note there are a nuumber of utility functions such as makeWallet and makeTokens which simplify the process. Also note that when populating the seed for the wallet, ensure that it is unique accross all the tests by using a naming convention similar to <test identifier>-1 e.g. TN-BASIC-0-1

• Executing the Transactions You may use functions such as commitReveal to simplify the execution, which wraps around the two-phase commit-reveal process required by the wallet. Please also check executeTokenTransaction in token.js which provides an example of how to simplify the execution even further. When you need to execute multiple transactions within a short amount of time, please use bumpTestTime, which artificially increase the time on the blockchain so you can bypass the default limitation of 1 operation per (30-second) interval for the wallet.

• Validating Wallet State: After completing the operation, you may validate the state of the wallet to ensure that the expected items have changed. Individual tests and assertions are used to compare the state of the wallet before the operation to the state after. getState is a helper function which you may use to take a snapshot of the wallet's state. A common pattern is to get the wallet's state prior to a transaction, execute the transaction, manually change part of the snapshot, then compare the latest snapshot with the modified state using assertStateEqual. See TN-BASIC-0 in token.js for an example.

Event Testing: After ensuring you have a basic positive test for the operation, you may expand on the testing coverage checking event emissions. See events.js for some example. The structure is similar to that of operational testing, but here we leverage events emitted by the wallet, and we add multiple scenarios for each operation.

Functional Testing: provides composability and scenario testing for use cases that occur in practice. These tests are written for each functional area. This is yet to be implemented. More details will be added soon.