From 80e726ffde7a9c714662971c509b75d83cbf8d5a Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Mon, 18 Dec 2023 16:28:34 -0500 Subject: [PATCH 1/7] fix testing page --- .../tutorials/writing_dapp/testing.md | 28 +++++++++++++------ .../end-to-end/src/sample-dapp/index.test.mjs | 18 +++++++++--- 2 files changed, 34 insertions(+), 12 deletions(-) diff --git a/docs/docs/dev_docs/tutorials/writing_dapp/testing.md b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md index 594bb81e5d9f..43ed93867380 100644 --- a/docs/docs/dev_docs/tutorials/writing_dapp/testing.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md @@ -21,18 +21,30 @@ 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. - ## Writing our test Now that we have a working test environment, we can write our first test for exercising the `transfer` function on the token contract. We will use the same `aztec.js` methods we used when building our dapp: @@ -43,7 +55,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/sample-dapp/index.test.mjs b/yarn-project/end-to-end/src/sample-dapp/index.test.mjs index 11424c9465d6..ad7282103da9 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 From 0c5ecaec5b97becc82216d9a2d4d0a24c219acab Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Mon, 18 Dec 2023 16:31:05 -0500 Subject: [PATCH 2/7] add tip --- docs/docs/dev_docs/tutorials/writing_dapp/testing.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/docs/dev_docs/tutorials/writing_dapp/testing.md b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md index 43ed93867380..2265bac5b2ee 100644 --- a/docs/docs/dev_docs/tutorials/writing_dapp/testing.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md @@ -45,6 +45,10 @@ Let's set up our test suite. We'll make sure the Sandbox is running, create two #include_code setup yarn-project/end-to-end/src/sample-dapp/index.test.mjs javascript +:::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 Now that we have a working test environment, we can write our first test for exercising the `transfer` function on the token contract. We will use the same `aztec.js` methods we used when building our dapp: From f902a67173c02ec2a69b20339fdd6e67db386c86 Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Mon, 18 Dec 2023 16:53:26 -0500 Subject: [PATCH 3/7] how to use debug options --- docs/docs/dev_docs/tutorials/testing.md | 10 ++++++++++ yarn-project/end-to-end/src/e2e_token_contract.test.ts | 2 ++ 2 files changed, 12 insertions(+) diff --git a/docs/docs/dev_docs/tutorials/testing.md b/docs/docs/dev_docs/tutorials/testing.md index e13c00c2ce68..f005db686a95 100644 --- a/docs/docs/dev_docs/tutorials/testing.md +++ b/docs/docs/dev_docs/tutorials/testing.md @@ -80,6 +80,16 @@ 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 private data tree, new nullifiers, public data writes, new L2 to L1 messages, new contract information and newly visible notes. + +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 + +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/yarn-project/end-to-end/src/e2e_token_contract.test.ts b/yarn-project/end-to-end/src/e2e_token_contract.test.ts index 5acdf39a0dec..95af7828e27c 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 From b721dd0665a6c430288f68d90a45be5929d6e8a0 Mon Sep 17 00:00:00 2001 From: josh crites Date: Tue, 19 Dec 2023 13:32:58 -0500 Subject: [PATCH 4/7] Update docs/docs/dev_docs/tutorials/testing.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jan Beneš --- docs/docs/dev_docs/tutorials/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/tutorials/testing.md b/docs/docs/dev_docs/tutorials/testing.md index f005db686a95..f14ef31a0ae8 100644 --- a/docs/docs/dev_docs/tutorials/testing.md +++ b/docs/docs/dev_docs/tutorials/testing.md @@ -82,7 +82,7 @@ Instead of creating new accounts in our test suite, we can use the ones already ### 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 private data tree, new nullifiers, public data writes, new L2 to L1 messages, new contract information and newly visible notes. +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. 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. From 7d37e94f192d80c60587724c4d86a09fc69f1bcf Mon Sep 17 00:00:00 2001 From: josh crites Date: Tue, 19 Dec 2023 13:33:26 -0500 Subject: [PATCH 5/7] Update docs/docs/dev_docs/tutorials/testing.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jan Beneš --- docs/docs/dev_docs/tutorials/testing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docs/dev_docs/tutorials/testing.md b/docs/docs/dev_docs/tutorials/testing.md index f14ef31a0ae8..3c30bdf23c1c 100644 --- a/docs/docs/dev_docs/tutorials/testing.md +++ b/docs/docs/dev_docs/tutorials/testing.md @@ -88,6 +88,8 @@ If a note doesn't appear when you expect it to, check the visible notes returned #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 From 8be789eb3686228c7f7761039f5ae4dbef9729f2 Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Tue, 19 Dec 2023 13:34:34 -0500 Subject: [PATCH 6/7] add note on where logs are printed --- docs/docs/dev_docs/tutorials/testing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docs/dev_docs/tutorials/testing.md b/docs/docs/dev_docs/tutorials/testing.md index f005db686a95..2b6e175f01ba 100644 --- a/docs/docs/dev_docs/tutorials/testing.md +++ b/docs/docs/dev_docs/tutorials/testing.md @@ -84,6 +84,8 @@ Instead of creating new accounts in our test suite, we can use the ones already 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 private data tree, new nullifiers, public data writes, new L2 to L1 messages, new contract information and newly visible notes. +This debug information will be printed in the terminal where you run your tests. + 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 From a8c6535494d98a3bb43a81e60622e6813e105e60 Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Tue, 19 Dec 2023 13:48:22 -0500 Subject: [PATCH 7/7] add clarity --- docs/docs/dev_docs/tutorials/testing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/dev_docs/tutorials/testing.md b/docs/docs/dev_docs/tutorials/testing.md index ccea511c3f4b..b0c3d5533276 100644 --- a/docs/docs/dev_docs/tutorials/testing.md +++ b/docs/docs/dev_docs/tutorials/testing.md @@ -84,14 +84,14 @@ Instead of creating new accounts in our test suite, we can use the ones already 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 printed in the terminal where you run your tests. +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. - +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