Mina Testing Utils

This repository contains a set of utilities for testing Mina zkapps:

Custom jest matchers
An interactive debugger to interact with locally deployed contracts
A contract (gates) sizer

Requirements

node +18 (nvm recommended)
o1js@0.12.*

Installing

In order to use this tool, you should install it as a dev dependency on your existing project, for example, one created using zkcli-app:

npm --save-dev install @atixlabs/mina-testing-utils

Using Jest matchers

Import it in your tests as follows:

// Import to extend the matchers
import '@atixlabs/mina-testing-utils';

describe('my test', () => {

  it('some test', async () => {

		// Matchers are automatically recognized by jest
    expect(Field(19)).toEqual(19);
    expect(app.someBooleanState).toBeFalse()
  })

You can refer to contract.test.ts for a running example.

Using the interactive debugger

After installing the package, you can run the interactive debugger as follows:

import { Field, SmartContract, state, State, method } from 'o1js';

/**
 * Basic Example
 * See https://docs.minaprotocol.com/zkapps for more info.
 *
 * The Add contract initializes the state variable 'num' to be a Field(1) value by default when deployed.
 * When the 'update' method is called, the Add contract adds Field(2) to its 'num' contract state.
 *
 * This file is safe to delete and replace with your own contract.
 */
export class Add extends SmartContract {
  @state(Field) num = State<Field>();

  init() {
    super.init();
    this.num.set(Field(1));
  }

  @method update() {
    const currentState = this.num.getAndAssertEquals();
    const newState = currentState.add(2);
    this.num.set(newState);
  }
}

❯ npx mina-testing-utils repl


 ███╗   ███╗ ██╗ ███╗   ██╗  █████╗      ████████╗ ███████╗ ███████╗ ████████╗ ██╗ ███╗   ██╗  ██████╗      ██╗   ██╗ ████████╗ ██╗ ██╗      ███████╗
 ████╗ ████║ ██║ ████╗  ██║ ██╔══██╗     ╚══██╔══╝ ██╔════╝ ██╔════╝ ╚══██╔══╝ ██║ ████╗  ██║ ██╔════╝      ██║   ██║ ╚══██╔══╝ ██║ ██║      ██╔════╝
 ██╔████╔██║ ██║ ██╔██╗ ██║ ███████║        ██║    █████╗   ███████╗    ██║    ██║ ██╔██╗ ██║ ██║  ███╗     ██║   ██║    ██║    ██║ ██║      ███████╗
 ██║╚██╔╝██║ ██║ ██║╚██╗██║ ██╔══██║        ██║    ██╔══╝   ╚════██║    ██║    ██║ ██║╚██╗██║ ██║   ██║     ██║   ██║    ██║    ██║ ██║      ╚════██║
 ██║ ╚═╝ ██║ ██║ ██║ ╚████║ ██║  ██║        ██║    ███████╗ ███████║    ██║    ██║ ██║ ╚████║ ╚██████╔╝     ╚██████╔╝    ██║    ██║ ███████╗ ███████║
 ╚═╝     ╚═╝ ╚═╝ ╚═╝  ╚═══╝ ╚═╝  ╚═╝        ╚═╝    ╚══════╝ ╚══════╝    ╚═╝    ╚═╝ ╚═╝  ╚═══╝  ╚═════╝       ╚═════╝     ╚═╝    ╚═╝ ╚══════╝ ╚══════╝



  

Please load the Mina REPL context by executing .loadMina before running any commands.


  
mina-testing-utils> .loadMina
✔ Snarky loaded successfully! You can access it through the mina object.

mina-testing-utils> let { Add } = await import("/Projects/yourProject/build/src/Add.js")

mina-testing-utils> let { priv: zkAppPrivateKey, pub: zkAppAddress } = mina.genKeyPair();

mina-testing-utils> let zkApp = new Add(zkAppAddress);

mina-testing-utils> let { privateKey: deployerKey, publicKey: deployerAccount } = mina.testAccounts[0];

mina-testing-utils> let txn = await mina.o1js.Mina.transaction(deployerAccount, () => {
  mina.o1js.AccountUpdate.fundNewAccount(deployerAccount);
  zkApp.deploy();
});

mina-testing-utils> await txn.prove();
mina-testing-utils> await txn.sign([deployerKey, zkAppPrivateKey]).send();

mina-testing-utils> console.log("Stored number in state is: ", zkApp.num.get().toString())
Stored number in state is:  1

See it in action:

Using the contract sizer

This tool also allows you to keep track of the amount of gates the contracts you create are creating thus giving an idea of the complexity it will involve using them. To try it, run:

npx mina-testing-utils circuits-sizer build/src/test-contract.js

Bear in mind you need to compile them first (if zkapp-cli is being used, it should be npm run build).

See it in action:

Development

Requirements

nodejs +18

Setup

npm install

Testing

npm test

Trying on a zkapp-cli local app

Note: npm link seems to be messing around with o1js import resulting in multiple errors therefore follow this steps in order to use a local version of this lib:

# generate your zkapp as you would do normally, see https://docs.minaprotocol.com/zkapps/how-to-write-a-zkapp
zk example

# build the library
npm run build
# generate a tar file in any folder as pleased
npm run dev-pack -- --pack-destination /tmp/ 

# install the library in your zkapp
cd example && npm install --save-dev /tmp/mina-testing-utils-0.0.1.tgz