Implementing On-Chain Tests for an NFT Marketplace Example Repo

[idea404]

Adding On-Chain Tests to nft-tutorial

I've been looking into way to implement simulation/integration tests into the nft-tutorial repository from near-examples and was told to have a look at this repo. I'm very happy I found it as it's been manageable to implement and intuitive in its syntax. For the readers interested in the code feel free to browse around this PR.

I'll share some takeaways from my experience implementing this testing framework which I hope can help people reading (and me too since I'm sure there's plenty that can be done better!):

• Configuration - your sim tests folder requires: a __tests__ folder containing your .ts tests and helpers, a ava.config.cjs file, a ava.testnet.config.cjs file, a tsconfig.json file and of course a package.json.
• Setup - initializing the on-chain environment for your smart contracts and some test accounts for use in test cases.
• Development Flow - refactoring as more test cases are implemented and using call, call_raw and the test functions to assert output.

Configuration

Running the default npx near-workspaces-init test script command near-workspaces-ava directly would not run the test:tesnet script in my package.json file, so I simplified it to something I could understand and yet still made use of near-workspaces-ava:

{
  "scripts": {
    "test:sandbox": "near-workspaces-ava --config ./ava.config.cjs --verbose --timeout=10m",
    "test:testnet": "near-workspaces-ava --config ./ava.testnet.config.cjs --verbose --timeout=10m",
    "test": "yarn test:sandbox && yarn test:testnet"
  },
  "devDependencies": {
    "near-workspaces-ava": "1.0.0",
    "ts-node": "^10.7.0"
  }
}

Setup

As nft-tutorial had two smart contracts, my initialization function would need to deploy both smart contracts to the chain to setup the testing environment. While coding this, I looked at the lib.rs files for both contract folders to see what function needed to be called (and with parameters) to initialize the contract once it is deployed. Here's what I ended up with:

import { Workspace } from "near-workspaces-ava";

export const workspace = Workspace.init(async ({ root }) => {
  const alice = await root.createAccount("alice");
  const bob = await root.createAccount("bob");
  const charlie = await root.createAccount("charlie");

  const nft_contract = await root.createAndDeploy(
    "nft-contract",
    "../out/main.wasm",
    {
      method: "new_default_meta",
      args: { owner_id: root },
    }
  );

  const market_contract = await root.createAndDeploy(
    "nft-market",
    "../out/market.wasm",
    {
      method: "new",
      args: { owner_id: root },
    }
  );

  return { alice, bob, charlie, nft_contract, market_contract };
});

Development Flow

I started with simple cases such as minting an NFT, like here this one (in test_contract.ava.ts):

workspace.test(
  "nft contract: nft mint call",
  async (test, { nft_contract, alice }) => {
    const request_payload = {
      token_id: "TEST123",
      metadata: {
        title: "LEEROYYYMMMJENKINSSS",
        description: "Alright time's up, let's do this.",
        media:
          "https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse3.mm.bing.net%2Fth%3Fid%3DOIP.Fhp4lHufCdTzTeGCAblOdgHaF7%26pid%3DApi&f=1",
      },
      receiver_id: alice,
    };
    await alice.call(
      nft_contract,
      "nft_mint",
      request_payload,
      defaultCallOptions()
    );

    const tokens = await nft_contract.view("nft_tokens");
    const expected = [
      {
        approved_account_ids: {},
        metadata: {
          copies: null,
          description: "Alright time's up, let's do this.",
          expires_at: null,
          extra: null,
          issued_at: null,
          media:
            "https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse3.mm.bing.net%2Fth%3Fid%3DOIP.Fhp4lHufCdTzTeGCAblOdgHaF7%26pid%3DApi&f=1",
          media_hash: null,
          reference: null,
          reference_hash: null,
          starts_at: null,
          title: "LEEROYYYMMMJENKINSSS",
          updated_at: null,
        },
        owner_id: alice.accountId,
        royalty: {},
        token_id: "TEST123",
      },
    ];
    test.deepEqual(tokens, expected, "Expected to find one minted NFT");
  }
);

And coding further, I realized I'd use the same code repeatedly to mint an NFT so I refactored that piece and sent it to a utils.ts folder and imported to my testing module. I was able to use it in a more involved failing test for cross contract transfers (in test_cross_contract.ava.ts) like here:

workspace.test(
  "cross contract: transfer NFT when listed on marketplace",
  async (test, { nft_contract, market_contract, alice, bob, charlie }) => {
    await mintNFT(alice, nft_contract);
    await payForStorage(alice, market_contract);

    const sale_price = "300000000000000000000000"; // sale price string in yoctoNEAR is 0.3 NEAR
    await placeNFTForSale(market_contract, alice, nft_contract, sale_price);

    await transferNFT(bob, market_contract, nft_contract);

    // purchase NFT
    const offer_payload = {
      nft_contract_id: nft_contract,
      token_id: "TEST123",
    };
    const result = await charlie.call_raw(
      market_contract,
      "offer",
      offer_payload,
      defaultCallOptions(
        DEFAULT_GAS + "0", // 10X default amount for XCC
        sale_price // Attached deposit must be greater than or equal to the current price
      )
    );

    // assert expectations
    // NFT has same owner
    const view_payload = {
      token_id: "TEST123",
    };
    const token_info = await nft_contract.view("nft_token", view_payload);
    test.is(
      token_info["owner_id"],
      bob.accountId, // NFT was transferred to bob
      "NFT should have bob as owner"
    );
    // Unauthorized error should be found
    test.regex(result.promiseErrorMessages.join("\n"), /Unauthorized+/);
  }
);

Let me know your thoughts! I'm always happy to see cleaner, more efficient and better-organized code 🤓