diff --git a/docs/docs/dev_docs/tutorials/testing.md b/docs/docs/dev_docs/tutorials/testing.md index e13c00c2ce6..b0c3d553327 100644 --- a/docs/docs/dev_docs/tutorials/testing.md +++ b/docs/docs/dev_docs/tutorials/testing.md @@ -80,6 +80,20 @@ Instead of creating new accounts in our test suite, we can use the ones already #include_code use-existing-wallets /yarn-project/end-to-end/src/guides/dapp_testing.test.ts typescript +### Using debug options + +You can use the `debug` option in the `wait` method to get more information about the effects of the transaction. At the time of writing, 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. + +If a note doesn't appear when you expect it to, check the visible notes returned by the debug options. See the following example for reference on how it's done in the token contract tests. + +#include_code debug /yarn-project/end-to-end/src/e2e_token_contract.test.ts typescript + +If the note appears in the visible notes and it contains the expected values there is probably an issue with how you fetch the notes. Check that the note getter (or note viewer) parameters are set correctly. If the note doesn't appear, ensure that you have emitted the corresponding encrypted log (usually by passing in a `broadcast = true` param to the `create_note` function). You can also check the Sandbox logs to see if the `emitEncryptedLog` was emitted. Run `export DEBUG="aztec:\*" before spinning up sandbox to see all the logs. + +For debugging and logging in Aztec contracts, see [this page](../debugging/main.md). + ## Assertions We will now see how to use `aztec.js` to write assertions about transaction statuses, about chain state both public and private, and about logs. diff --git a/docs/docs/dev_docs/tutorials/writing_dapp/testing.md b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md index 594bb81e5d9..2265bac5b2e 100644 --- a/docs/docs/dev_docs/tutorials/writing_dapp/testing.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md @@ -21,17 +21,33 @@ We'll need to [install and run the Sandbox](../../cli/sandbox-reference.md#insta Create a new file `src/index.test.mjs` with the imports we'll be using and an empty test suite to begin with: ```js -import { Contract, createAccount } from "@aztec/aztec.js"; -import TokenContractArtifact from "../contracts/token/target/Token.json" assert { type: "json" }; - -describe("token", () => {}); +import { + Contract, + ExtendedNote, + Fr, + Note, + computeMessageSecretHash, + createAccount, + createPXEClient, + waitForSandbox, +} from "@aztec/aztec.js"; +import { TokenContractArtifact } from "@aztec/noir-contracts/artifacts"; + +const { + PXE_URL = "http://localhost:8080", + ETHEREUM_HOST = "http://localhost:8545", +} = process.env; + +describe("token contract", () => {}); ``` -Let's set up our test suite. We'll start [a new Sandbox instance within the test](../testing.md#running-sandbox-in-the-nodejs-process), create two fresh accounts to test with, and deploy an instance of our contract. The `aztec-sandbox` and `aztec.js` provide the helper functions we need to do this: +Let's set up our test suite. We'll make sure the Sandbox is running, create two fresh accounts to test with, and deploy an instance of our contract. `aztec.js` provides the helper functions we need to do this: #include_code setup yarn-project/end-to-end/src/sample-dapp/index.test.mjs javascript -Note that, since we are starting a new Sandbox instance, we need to `stop` it in the test suite teardown. Also, even though the Sandbox runs within our tests, we still need a running Ethereum development node. Make sure you are running [Anvil](https://book.getfoundry.sh/anvil/), [Hardhat Network](https://hardhat.org/hardhat-network/docs/overview), or [Ganache](https://trufflesuite.com/ganache/) along with your tests. +:::tip +Instead of creating new accounts in our test suite, we can use the ones already initialized by the Sandbox upon startup. This can provide a speed boost to your tests setup. However, bear in mind that you may accidentally introduce an interdependency across test suites by reusing the same accounts. Read more [here](../testing.md#using-sandbox-initial-accounts). +::: ## Writing our test @@ -43,7 +59,7 @@ In this example, we assert that the `recipient`'s balance is increased by the am ## Running our tests -With a local Ethereum development node running in port 8545, we can run our `jest` tests using `yarn`. The quirky syntax is due to [jest limitations in ESM support](https://jestjs.io/docs/ecmascript-modules), as well as not picking up `mjs` file by default: +We can run our `jest` tests using `yarn`. The quirky syntax is due to [jest limitations in ESM support](https://jestjs.io/docs/ecmascript-modules), as well as not picking up `mjs` file by default: ```sh yarn node --experimental-vm-modules $(yarn bin jest) --testRegex '.*\.test\.mjs$' diff --git a/yarn-project/end-to-end/src/e2e_token_contract.test.ts b/yarn-project/end-to-end/src/e2e_token_contract.test.ts index 5acdf39a0de..95af7828e27 100644 --- a/yarn-project/end-to-end/src/e2e_token_contract.test.ts +++ b/yarn-project/end-to-end/src/e2e_token_contract.test.ts @@ -172,7 +172,9 @@ describe('e2e_token_contract', () => { it('redeem as recipient', async () => { await addPendingShieldNoteToPXE(0, amount, secretHash, txHash); const txClaim = asset.methods.redeem_shield(accounts[0].address, amount, secret).send(); + // docs:start:debug const receiptClaim = await txClaim.wait({ debug: true }); + // docs:end:debug expect(receiptClaim.status).toBe(TxStatus.MINED); tokenSim.redeemShield(accounts[0].address, amount); // 1 note should be created containing `amount` of tokens diff --git a/yarn-project/end-to-end/src/sample-dapp/index.test.mjs b/yarn-project/end-to-end/src/sample-dapp/index.test.mjs index 11424c9465d..ad7282103da 100644 --- a/yarn-project/end-to-end/src/sample-dapp/index.test.mjs +++ b/yarn-project/end-to-end/src/sample-dapp/index.test.mjs @@ -1,12 +1,24 @@ import { createSandbox } from '@aztec/aztec-sandbox'; -import { Contract, ExtendedNote, Fr, Note, computeMessageSecretHash, createAccount } from '@aztec/aztec.js'; +import { + Contract, + ExtendedNote, + Fr, + Note, + computeMessageSecretHash, + createAccount, + createPXEClient, + waitForSandbox, +} from '@aztec/aztec.js'; import { TokenContractArtifact } from '@aztec/noir-contracts/artifacts'; +const { PXE_URL = 'http://localhost:8080', ETHEREUM_HOST = 'http://localhost:8545' } = process.env; + describe('token', () => { // docs:start:setup let pxe, stop, owner, recipient, token; beforeAll(async () => { - ({ pxe, stop } = await createSandbox()); + const pxe = createPXEClient(PXE_URL); + await waitForSandbox(pxe); owner = await createAccount(pxe); recipient = await createAccount(pxe); @@ -24,8 +36,6 @@ describe('token', () => { await token.methods.redeem_shield({ address: owner.getAddress() }, initialBalance, secret).send().wait(); }, 120_000); - - afterAll(() => stop()); // docs:end:setup // docs:start:test