Cadence testing framework improvements

[m-Peter]

Closes #2076
Companion PR: onflow/cadence-tools#181

Description

Adding the following improvements:

• Allow rolling back at a specific block height
• Add helper function to assert error message on ScriptResult/TransactionResult

Sample usage:

import Test

pub let blockchain = Test.newEmulatorBlockchain()
pub let account = blockchain.createAccount()

// Retrieve current block height
pub let height = getCurrentBlockHeight(blockchain: blockchain)

// Reset (rollback) the blockchain to a given block height
blockchain.reset(height)

pub let script = Test.readFile("../scripts/get_integer_traits.cdc")
pub let result = blockchain.executeScript(script, [])

// Assert that a script/transaction errored and the error message contains a specified sub-string
Test.assertError(result, errorMessage: "exceeding limit")

---

• Targeted PR against master branch
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work
• Code follows the standards mentioned here
• Updated relevant documentation
• Re-reviewed Files changed in the Github PR explorer
• Added appropriate labels

[codecov]

Codecov Report

Merging #2696 (ff06b1d) into master (96403f2) will increase coverage by 0.00%.
The diff coverage is 60.00%.

@@           Coverage Diff           @@
##           master    #2696   +/-   ##
=======================================
  Coverage   79.10%   79.10%           
=======================================
  Files         333      333           
  Lines       78192    78194    +2     
=======================================
+ Hits        61851    61855    +4     
+ Misses      14048    14046    -2     
  Partials     2293     2293           

Flag	Coverage Δ
unittests	79.10% <60.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Changed	Coverage Δ
runtime/stdlib/test_emulatorbackend.go	53.01% <60.00%> (+0.61%)	⬆️

[turbolent]

In general, these additions are great ideas! The FLOW token helpers I'm not so sure about (mintFlow and burnFlow).

Though they are obviously convenient, the Cadence repo is probably not the best place to add them. We're trying to keep Cadence chain-agnostic / independent of Flow. Unfortunately there have been some places where we were not strict (e.g. naming of built-in events), but it would be nice to at least avoid adding new code tying Cadence to Flow, i.e. here the assumption that there is a FLOW token.

Maybe these helper functions could be added upstream, e.g. in cadence-tools/test? That way we would not force embedders of Cadence to provide the FLOW token-specific functionality.

[satyamakgec]

LGTM

[m-Peter]

In general, these additions are great ideas! The FLOW token helpers I'm not so sure about (mintFlow and burnFlow).

Though they are obviously convenient, the Cadence repo is probably not the best place to add them. We're trying to keep Cadence chain-agnostic / independent of Flow. Unfortunately there have been some places where we were not strict (e.g. naming of built-in events), but it would be nice to at least avoid adding new code tying Cadence to Flow, i.e. here the assumption that there is a FLOW token.

Maybe these helper functions could be added upstream, e.g. in cadence-tools/test? That way we would not force embedders of Cadence to provide the FLOW token-specific functionality.

@turbolent Thanks for the feedback 🙏 You've got a good point. I wanted to add the helper functions as part of the Test.Blockchain type, but I wasn't satisfied in the first place, because I had to embed the scripts/transactions in Cadence strings. I have moved all 4 helper functions to the companion PR on the cadence-tools/test repository. The new API looks like this:

import Test
import BlockchainHelpers

pub let blockchain = Test.newEmulatorBlockchain()
pub let account = blockchain.createAccount()

// Retrieve current block height
let height = getCurrentBlockHeight(blockchain: blockchain)

// Reset (rollback) the blockchain to a given block height
blockchain.reset(height)

// Retrieve the Flow token balance of a test account
let balance = getFlowBalance(for: account, blockchain: blockchain)

// Mint a given amount of Flow tokens to a specified test account
mintFlow(to: account, amount: 1500.0, blockchain: blockchain)

// Burn a given amount of Flow tokens from a specified test account
burnFlow(from: account, amount: 500.0, blockchain: blockchain)

We have to pass around the blockchain instance, to all these 4 helper functions, as they are no longer defined on the Test.Blockchain type.

[turbolent]

Nice!