Test Scenario

Test scenario is the current industry standard to ensure a contract has the expected behavior. Basically a test is a program that originates the contract(s), calls them and checks the storage value(s) and account(s) balances.

This article presents how to write and execute tests with Completium.

Completium JS library#

Completium provides a Javascript programming library to program interactions with contracts. It benefits from the configuration of endpoints and accounts established with the CLI.

Before using $completium-cli as a programming library, install the CLI to configure endpoint and account(s).

Create test project#

Follow the standard npm process to create a javascript project and install completium-cli:

$ mkdir test
$ cd test
$ npm init -y
$ npm i @completium/completium-cli


The following example illustrates how to test the State machine contract of the Archetype tutorial.

The goal is to check whether the contract is in the right state after a series of calls to init, inc_value twice and complete entrypoints, and to check whether the caller's balance is unchanged while transferring 5tz to init (within cost of transactions).

const assert = require('assert');
const Completium = require('@completium/completium-cli');
const test = async () => {
const completium = new Completium ();
// Scenario
const balance_before = (await completium.getBalance()).toNumber();
var cost = 0;
var op = await completium.originate('state_machine.arl');
cost += op.cost.toNumber();
// send 5tz to contract
var op = await completium.call("state_machine", {
entry : "init",
amount: "5tz" });
cost += op.cost.toNumber();
var op = await completium.call("state_machine", { entry : "inc_value" });
cost += op.cost.toNumber();
var op = await completium.call("state_machine", { entry : "inc_value" });
cost += op.cost.toNumber();
// Should return the 5tz sent with `init`
var op = await completium.call("state_machine", { entry : "complete" });
cost += op.cost.toNumber();
// Test final state and balance
const storage = await completium.getStorage("state_machine");
const balance = (await completium.getBalance()).toNumber();
assert(storage._state == 3, "Invalid contract state");
assert(balance == balance_before - cost, "Invalid caller balance");

The cost of transactions is accumulated in the local cost variable. It is used to test that the caller has got back the 5 tezies send to init entrypoint.

The script is using the current account and endpoint, shown with the Completium CLI commands:

$ completium-cli show endpoint
Current network: edo
Current endpoint: https://edonet-tezos.giganode.io
$ completium-cli show account
Current account: admin
Public key hash: tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb
Balance on sandbox: 9998.466387

This means the script is using the edo network with the account admin. It is possible to programmatically switch account and endpoint from within the test scenario.

Run test#

Edit the package file to set the test command:

"name": "demo",
"version": "1.0.0",
"description": "",
"main": "test.js",
"scripts": {
"test": "node test.js"
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {
"@completium/completium-cli": "^0.1.8"

Launch the test with:

npm test


$completium-cli provides the possibility to run the scenario on a local sandbox network.

In order to launch the test in a sandbox, run the following script:

completium-cli start sandbox
completium-cli set endpoint http://localhost:20000
npm test
completium-cli stop sandbox