Testing Aztec.nr contracts with TypeScript

In this guide we will cover how to interact with your Aztec.nr smart contracts in a testing environment to write automated tests for your apps.

Prerequisites

• A compiled contract with TS interface (read how to compile)
• Your sandbox running (read getting started)

Create TS file and install libraries

Pick where you'd like your tests to live and create a Typescript project.

You will need to install Aztec.js:

yarn add @aztec/aztecjs

You can use aztec.js to write assertions about transaction statuses, about chain state both public and private, and about logs.

Import relevant libraries

Import aztecjs. This is an example of some functions and types you might need in your test:

imports

import { createAccount, getDeployedTestAccountsWallets } from '@aztec/accounts/testing';
import { type AccountWallet, CheatCodes, Fr, type PXE, TxStatus, createPXEClient, waitForPXE } from '@aztec/aztec.js';

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L1-L4}}

You should also import the Typescript class you generated:

import_contract

import { TestContract } from '@aztec/noir-contracts.js/Test';

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L5-L7}}

Create a PXE client

Currently, testing Aztec.nr smart contracts means testing them against the PXE that runs in the local sandbox. Create a PXE client:

create_pxe_client

const pxe = createPXEClient(PXE_URL);
await waitForPXE(pxe);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L18-L21}}

and use the accounts that are initialized with it:

use-existing-wallets

pxe = createPXEClient(PXE_URL);
[owner, recipient] = await getDeployedTestAccountsWallets(pxe);
token = await TokenContract.deploy(owner, owner.getCompleteAddress(), 'TokenName', 'TokenSymbol', 18)
  .send()
  .deployed();

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L57-L63}}

Alternatively, you can create a new account..

Write tests

Calling and sending transactions

You can send transactions within your tests with Aztec.js. Read how to do that in these guides:

• Call a view (unconstrained) function
• Send a transaction

Using debug options

You can use the debug option in the wait method to get more information about the effects of the transaction. This includes information about new note hashes added to the note hash tree, new nullifiers, public data writes, new L2 to L1 messages, new contract information, and newly visible notes.

This debug information will be populated in the transaction receipt. You can log it to the console or use it to make assertions about the transaction.

debug

const tx = await asset.methods.transfer(accounts[1].address, totalBalance).send().wait({ debug: true });

^{_{Source code: yarn-project/end-to-end/src/e2e_token_contract/private_transfer_recursion.test.ts#L38-L40}}

You can also log directly from Aztec contracts. Read this guide for some more information.

Examples

A private call fails

We can check that a call to a private function would fail by simulating it locally and expecting a rejection. Remember that all private function calls are only executed locally in order to preserve privacy. As an example, we can try transferring more tokens than we have, which will fail an assertion with the Balance too low error message.

local-tx-fails

const call = token.methods.transfer(recipient.getAddress(), 200n);
await expect(call.prove()).rejects.toThrow(/Balance too low/);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L144-L147}}

Under the hood, the send() method executes a simulation, so we can just call the usual send().wait() to catch the same failure.

local-tx-fails-send

const call = token.methods.transfer(recipient.getAddress(), 200n);
await expect(call.send().wait()).rejects.toThrow(/Balance too low/);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L151-L154}}

A transaction is dropped

We can have private transactions that work fine locally, but are dropped by the sequencer when tried to be included due to a double-spend. In this example, we simulate two different transfers that would succeed individually, but not when both are tried to be mined. Here we need to send() the transaction and wait() for it to be mined.

tx-dropped

const call1 = token.methods.transfer(recipient.getAddress(), 80n);
const call2 = token.methods.transfer(recipient.getAddress(), 50n);

const provenCall1 = await call1.prove();
const provenCall2 = await call2.prove();

await provenCall1.send().wait();
await expect(provenCall2.send().wait()).rejects.toThrow(/dropped/);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L158-L167}}

A public call fails locally

Public function calls can be caught failing locally similar to how we catch private function calls. For this example, we use a TokenContract (GitHub link) instead of a private one.

local-pub-fails

const call = token.methods.transfer_public(owner.getAddress(), recipient.getAddress(), 1000n, 0);
await expect(call.prove()).rejects.toThrow(U128_UNDERFLOW_ERROR);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L171-L174}}

A public call fails on the sequencer

We can ignore a local simulation error for a public function via the skipPublicSimulation. This will submit a failing call to the sequencer, who will include the transaction, but without any side effects from our application logic. Requesting the receipt for the transaction will also show it has a reverted status.

pub-reverted

const call = token.methods.transfer_public(owner.getAddress(), recipient.getAddress(), 1000n, 0);
const receipt = await call.send({ skipPublicSimulation: true }).wait({ dontThrowOnRevert: true });
expect(receipt.status).toEqual(TxStatus.APP_LOGIC_REVERTED);
const ownerPublicBalanceSlot = cheats.aztec.computeSlotInMap(6n, owner.getAddress());
const balance = await pxe.getPublicStorageAt(token.address, ownerPublicBalanceSlot);
expect(balance.value).toEqual(100n);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L178-L185}}

WARN Error processing tx 06dc87c4d64462916ea58426ffcfaf20017880b353c9ec3e0f0ee5fab3ea923f: Assertion failed: Balance too low.

Querying state

We can check private or public state directly rather than going through view-only methods, as we did in the initial example by calling token.methods.balance().simulate().

To query storage directly, you'll need to know the slot you want to access. This can be checked in the contract's Storage definition directly for most data types. However, when it comes to mapping types, as in most EVM languages, we'll need to calculate the slot for a given key. To do this, we'll use the CheatCodes utility class:

calc-slot

cheats = await CheatCodes.create(ETHEREUM_HOST, pxe);
// The balances mapping is indexed by user address
ownerSlot = cheats.aztec.computeSlotInMap(TokenContract.storage.balances.slot, ownerAddress);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L100-L104}}

Querying private state

Private state in the Aztec is represented via sets of private notes. We can query the Private Execution Environment (PXE) for all notes encrypted for a given user in a contract slot. For example, this gets all notes encrypted for the owner user that are stored on the token contract address and on the slot that was calculated earlier. To calculate the actual balance, it extracts the value of each note, which is the first element, and sums them up.

private-storage

const notes = await pxe.getIncomingNotes({
  owner: owner.getAddress(),
  contractAddress: token.address,
  storageSlot: ownerSlot,
  scopes: [owner.getAddress()],
});
const values = notes.map(note => note.note.items[0]);
const balance = values.reduce((sum, current) => sum + current.toBigInt(), 0n);
expect(balance).toEqual(100n);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L108-L118}}

Querying public state

Public state behaves as a key-value store, much like in the EVM. We can directly query the target slot and get the result back as a buffer. Note that we use the TokenContract (GitHub link) in this example, which defines a mapping of public balances on slot 6.

public-storage

await token.methods.mint_public(owner.getAddress(), 100n).send().wait();
const ownerPublicBalanceSlot = cheats.aztec.computeSlotInMap(6n, owner.getAddress());
const balance = await pxe.getPublicStorageAt(token.address, ownerPublicBalanceSlot);
expect(balance.value).toEqual(100n);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L122-L127}}

Logs

You can check the logs of events emitted by contracts. Contracts in Aztec can emit both encrypted and unencrypted events.

Querying unencrypted logs

We can query the PXE for the unencrypted logs emitted in the block where our transaction is mined. Logs need to be unrolled and formatted as strings for consumption.

unencrypted-logs

const value = Fr.fromString('ef'); // Only 1 bytes will make its way in there :( so no larger stuff
const tx = await testContract.methods.emit_unencrypted(value).send().wait();
const filter = {
  fromBlock: tx.blockNumber!,
  limit: 1, // 1 log expected
};
const logs = (await pxe.getUnencryptedLogs(filter)).logs;
expect(Fr.fromBuffer(logs[0].log.data)).toEqual(value);

^{_{Source code: yarn-project/end-to-end/src/guides/dapp_testing.test.ts#L131-L140}}

Cheats

The CheatCodes class, which we used for calculating the storage slot above, also includes a set of cheat methods for modifying the chain state that can be handy for testing.

Set next block timestamp

Since the rollup time is dependent on what "slot" the block is included in, time can be progressed by progressing slots. The duration of a slot is available by calling SLOT_DURATION() on the Rollup (code in Leonidas.sol).

You can then use the warp function on the EthCheatCodes to progress the underlying chain.

Further reading

• How to call a view transactions in Aztec.js
• How to send a transactions in Aztec.js
• How to deploy a contract in Aztec.js
• How to create an account in Aztec.js
• Cheat codes
• How to compile a contract.