CU-86dtu8tcn - Add boa test constructor to the documentation #1265
Conversation
docs/source/testing-and-debugging.md
Outdated
| Install [boa-test-constructor](https://pypi.org/project/boa-test-constructor/) with pip. We use this extension to run an isolated | ||
| test environment for smart contracts with a neo-go node. When installing boa-test-constructor, [neo-mamba](https://dojo.coz.io/neo3/mamba/index.html) | ||
| will be installed too. |
There was a problem hiding this comment.
It is worth mentioning that the packages can be installed directly when neo3-boa is installed by using pip install neo3-boa[test]
docs/source/testing-and-debugging.md
Outdated
| Then, create functions to test the expected behavior of your smart contract. To invoke or test invoke your smart | ||
| contract, use the `call` method from `SmartContractTestCase`. The two positional parameters are the name of the method |
There was a problem hiding this comment.
the user reading this documentation may not know the difference between invoke and test invoke, you can just write "To invoke your smart contract [...]" here
docs/source/testing-and-debugging.md
Outdated
| argument to set up the test environment. | ||
| Then, create functions to test the expected behavior of your smart contract. To invoke or test invoke your smart | ||
| contract, use the `call` method from `SmartContractTestCase`. The two positional parameters are the name of the method | ||
| you want to invoke and a list of its arguments. The keyword parameters are the return type, a list of signing accounts, |
There was a problem hiding this comment.
ensure that methodName, args and returnType are mandatory
docs/source/testing-and-debugging.md
Outdated
| To persist an invocation, use the `signing_accounts` parameter to pass a list of signing accounts when calling the | ||
| smart contract. If you don't pass it, then it will always be a test invoke. The `signers` parameter can be used | ||
| alongside the `signing_accounts` if you want to change the witness scope of the invocation, or by itself if you want to | ||
| test invoke but also define the signers of the transaction. |
There was a problem hiding this comment.
we are not going to explain what signers and witnesses scopes are in this file, can you link the neo documentation related to signers here to guide the user if it wants more information?
docs/source/testing-and-debugging.md
Outdated
| @classmethod | ||
| def setUpClass(cls) -> None: | ||
| super().setUpClass() | ||
| # you can name the account whatever you want, but the password needs to be "123" | ||
| cls.user1 = cls.node.wallet.account_new("123", "alice") | ||
| cls.genesis = cls.node.wallet.account_get_by_label("committee") | ||
|
|
||
| asyncio.run(cls.asyncSetupClass()) | ||
|
|
||
| @classmethod | ||
| async def asyncSetupClass(cls) -> None: | ||
| # this `transfer` method already uses the correct amount of decimals for the token | ||
| await cls.transfer(GAS, cls.genesis.script_hash, cls.user1.script_hash, 100) | ||
|
|
||
| # the smart contract I'm deploying is hello_world_with_deploy.py from the "Neo Methods" https://dojo.coz.io/neo3/boa/getting-started.html#neo-methods | ||
| cls.contract_hash = await cls.deploy("./smart_contract.nef", cls.genesis) |
There was a problem hiding this comment.
I think these code snippets should be along the texts that explain what to do, the text by itself does not help much without code to look into
If the user if following the documentation I don't think its test is going to look like this as the text before it suggests, there is mention to initiating accounts, but is not explicit that in this tutorial we're setting a user test account.
docs/source/testing-and-debugging.md
Outdated
| async def asyncSetupClass(cls) -> None: | ||
| # this `transfer` method already uses the correct amount of decimals for the token | ||
| await cls.transfer(GAS, cls.genesis.script_hash, cls.user1.script_hash, 100) | ||
|
|
||
| # the smart contract I'm deploying is hello_world_with_deploy.py from the "Neo Methods" https://dojo.coz.io/neo3/boa/getting-started.html#neo-methods | ||
| cls.contract_hash = await cls.deploy("./smart_contract.nef", cls.genesis) |
There was a problem hiding this comment.
It's worth mentioning that the test case run on a local chain that is going to reset each time the tests are executed, that's why the contract needs to be deployed and the user balance needs to me initialized
docs/source/testing-and-debugging.md
Outdated
| def setUpClass(cls) -> None: | ||
| super().setUpClass() | ||
| # you can name the account whatever you want, but the password needs to be "123" | ||
| cls.user1 = cls.node.wallet.account_new("123", "alice") |
There was a problem hiding this comment.
just for clarity sake, i think it's better to put the label first
| cls.user1 = cls.node.wallet.account_new("123", "alice") | |
| cls.user1 = cls.node.wallet.account_new(label="alice", password="123") |
| @classmethod | ||
| def setUpClass(cls) -> None: | ||
| super().setUpClass() | ||
| # you can name the account whatever you want, but the password needs to be "123" |
There was a problem hiding this comment.
is there a reason that the password needs to be "123"? is it a boa-test-constructor issue?
docs/source/testing-and-debugging.md
Outdated
| synchronous, so if you need to set up asynchronous tasks, you can create another async method and use it int the | ||
| `asyncio.run` method from `asyncio`. Common operations would be: creating accounts, deploying the smart contract, | ||
| selecting your "main" smart contract, and transferring GAS to the new accounts. |
There was a problem hiding this comment.
it is worth mentioning why the tests must be async:
the tests use a local chain to run the invocations and the communication with the chain is asynchronous, so anything that needs to interact with it (deploy, token transfers, vote, etc) must be awaited
No description provided.