near-runner-ava v1.0.0

near-runner + AVA

A thin wrapper around near-runner to make it easier to use with AVA and TypeScript. If you don't want AVA, use near-runner directly.

Write tests once, run them both on NEAR TestNet and a controlled NEAR Sandbox local environment.

Quick Start

near-runner-init is a one-time command to quickly initialize a project with near-runner-ava. You will need NodeJS installed. Then:

npx near-runner-init

It will:

• Add a near-runner directory to the folder where you ran the command. This directory contains all the configuration needed to get you started with near-runner-ava, and a __tests__ subfolder with a well-commented example test file.
• Create test.sh and test.bat scripts in the folder where you ran the command. These can be used to quickly run the tests in near-runner. Feel free to integrate test-running into your project in a way that makes more sense for you, and then remove these scripts.

• Install NPM dependencies using npm install. Most of the output you see when running the command comes from this step. You can skip this: npx near-runner-init --no-install.

  NodeJS: https://nodejs.dev/

Manual Install

1. Install.

   npm install --save-dev near-runner-ava # npm
   yarn add --dev near-runner-ava         # yarn

2. Configure.

   AVA currently requires that your project have its own AVA config file. Add a file called ava.config.cjs next to your package.json with the following contents:

   module.exports = require('near-runner-ava/ava.config.cjs');

   We also recommend using the near-runner-ava script to run your tests. This is mostly an alias for ava, and passes CLI arguments right through.

   "test": "near-runner-ava"

   Now you can run tests with npm run test or yarn test.

   If you want to write tests with TypeScript (recommended), you can add a tsconfig.json to your project root with the following contents:

   {"extends": "near-runner-ava/tsconfig.ava.json"}

   If you already have TypeScript set up and you don't want to extend the config from near-runner-ava, feel free to just copy the settings you want from tsconfig.ava.json.

3. Initialize.

   Make a __tests__ folder, make your first test file. Call it main.ava.ts if you're not sure what else to call it. The AVA config you extended above will find files that match the *.ava.(ts|js) suffix.

   In main.ava.ts, set up a runner with NEAR accounts, contracts, and state that will be used in all of your tests.

   import {Runner} from 'near-runner-ava';
   
   const runner = Runner.create(async ({root}) => {
      const alice = await root.createAccount('alice');
      const contract = await root.createAndDeploy(
        'contract-account-name',
        'path/to/compiled.wasm'
      );
   
      // make other contract calls that you want as a starting point for all tests
   
      return {alice, contract};
   });

4. Write tests.

    runner.test("does something", async (test, { alice, contract }) => {
      await alice.call(contract, "some_update_function", {
        some_string_argument: "cool",
        some_number_argument: 42,
      });
      const result = await contract.view("some_view_function", {
        account_id: alice,
      });
      // When --verbose option is used this will print neatly underneath the test in the output.
      test.log(result)
      test.is(result, "whatever");
    });
   
    runner.test("does something else", async (test, { alice, contract }) => {
      const result = await contract.view("some_view_function", {
        account_id: alice,
      });
      test.is(result, "some default");
    });

   runner.test is added to near-runner by near-runner-ava, and is shorthand for:

   import avaTest from 'ava';
   
   avaTest('does something', async test => {
     await runner.run(async ({…}) => {
       // tests go here
     });
   });

   Where test and t come from AVA and runner.run comes from near-runner.

See the __tests__ directory for more examples.