Build on Flow: JS Testing - 1. Introduction

Intro

One of the most important parts of software development is Testing. It helps ensure that the product meets the requirements and is fit for the purpose. Testing allows to detect bugs and errors in the software, which in turn makes it more reliable and efficient.

It's especially important for any blockchain project, considering the immutable nature of blockchains. Errors that could easily be fixed in Web2 application usually are irreversable, when changes are introducted to the ledger.

Flow Network is using Cadence - a new Domain Specific Language designed to make writing smart contracts easier and more accessible. Cadence is a statically typed, high-level smart contract language that simplifies development by allowing developers to write complex logic that can be deployed and executed on the the Flow Network.

Testing Options

There are several paths you can go to test your Cadence code:

• Create testbed based on Flow Go SDK and inspired by TopShot
• Use amazing Overflow by one of the most prolific community members Bjarte S. Karlsen
• Use Cadence Testing Framework
• Use Flow JS Testing Framework

In this series we will explore the last option.

What is Flow JS Testing?

Flow JS Testing is a library of utility methods, which in conjuction with Flow CLI provides developers the ability to write tests for Cadence using Javascript and testing solutions like Jest

It have all the necessary capabilities to get blockchain interaction out of the way and allow you to focus on writing "human-readable" tests. Here are some of them:

• start/stop Flow Blockchain emulator
• create and manage accounts
• deploy contracts
• execute scripts and send transactions signed by one or multiple parties
• helpful Jest assertions for passing/failing interactions

🖐 Please note, framework is not restricting you to only use Jest, even though all examples and tutorials utilizing it.

Let's give it a try and create a simple test, which will execute the script on Emulator and return a value, which we can then compare to expected result.

Prerequisites

You will need to install Flow CLI in order to be able to spin up Flow Emulator. Follow instructions for your OS on Developer Portal.

Installation

Setting up all the necessary configs and environment is quite taxating 😩. That is exactly the reason, why we made handy init function for you! Open the terminal in the root of your project, copy/paste following block and press Enter:

mkdir test &&
cd test &&
npx @onflow/flow-js-testing init

This will run all the necessary steps, create babel and jest configration as well as install dependecies neededd to run the tests.

Now let's create our first test file! You can copy/paste on of the examples from links we've provided below or simply run:

npx @onflow/flow-js-testing make simple

Where simple is the name of the file and test suite - series of tests enclosed in describe block.

Open the file in your prefered editor.
Import executeScript from @onflow/flow-js-testing:

import { emulator, init } from "@onflow/flow-js-testing";
import { executeScript } from "@onflow/flow-js-testing"

Update the only test block defined there:

test("basic assertion", async () => {
  const [result] = await executeScript({
    code: `
      pub fun main():Int{
        return 42
      }
    `
  })
  expect(result).toBe("42")
})

executeScript method will return a tupple [result, error, logs]. This time we only care about result value so we can drop error and logs values - one of the following articles will cover those in details.

☝ Even though we are returning Int value it is still a string! You will need to handle conversions yourself. At least for now 😅

Now run your test with:

jest

Congratulations! You succesfully tested and confirmed your setup is working properly 🎉

Next time we will create basic smart-contract and interact with it. Stay tuned! 👋

Link and Sources

• Flow Developer Portal - Detailed information about Flow blockchain, tutorials, tools and everything you need
• Flow JS Testing - API Reference - JS Testing API Reference
• Flow JS Testing - Examples - Multiple examples for common patterns and interactions
• KittyItems Example - Real-life example of JS Testing Framework application for Cadence testing