diff --git a/README.md b/README.md index 9c86b16beb..d9a020b482 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,70 @@ -# Ape Framework +# Quick Start -Ape is a framework for Web3 Python applications and smart contracts, with advanced functionality for testing, deployment, and on-chain interactions. +## Prerequisite -See [website](https://apeworx.io/) and [documentation](https://docs.apeworx.io/ape). +In the latest release, Ape requires: -## Dependencies +- Linux or macOS +- Python 3.7.X or later -* [python3](https://www.python.org/downloads) version 3.7 or greater, python3-dev +**Windows**: + +1. Install Windows Subsystem Linux + [(WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) +2. Choose Ubuntu 20.04 OR Any other Linux Distribution with Python + 3.7.X or later + +Please make sure you are using Python 3.7.X or later. + +Check your python command by entering + +```bash +python3 --version +``` ## Installation +**Suggestion**: Create a virtual environment using `virtualenv` or `venv.` + +You may skip this creating a virtual environment if you know you don\'t +require one for your use case. + +* [virtualenv](https://pypi.org/project/virtualenv/) +* [venv](https://docs.python.org/3/library/venv.html) + +Create your virtual environment folder + +```bash +python3 -m venv /path/to/new/environment +source /bin/activate +``` + +You should see `(name_of_venv) DESKTOP_NAME:~/path:$`. +To deactivate the virtual environment, do: + +```bash +deactivate +``` + +Now that your Python version is later than 3.7.X and you have created a +virtual environment. Let\'s install Ape! There are 3 ways to install +ape: `pip`, `setuptools`, or `Docker`. + ### via `pip` -You can install the latest release via [`pip`](https://pypi.org/project/pip/): +You can install the latest release via +[pip](https://pypi.org/project/pip/): ```bash +pip install -U pip pip install eth-ape ``` ### via `setuptools` -You can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version: +You can clone the repository and use +[setuptools](https://github.com/pypa/setuptools) for the most up-to-date +version: ```bash git clone https://github.com/ApeWorX/ape.git @@ -30,12 +74,11 @@ python3 setup.py install ### via `docker` -Please visit our [Dockerhub](https://hub.docker.com/repository/docker/apeworx/ape) for more details on using Ape with Docker. +Please visit our +[Dockerhub](https://hub.docker.com/repository/docker/apeworx/ape) for +more details on using Ape with Docker. -example commands: - -compiling: -``` +```bash docker run \ --volume $HOME/.ape:/root/.ape \ --volume $HOME/.vvm:/root/.vvm \ @@ -45,74 +88,157 @@ docker run \ apeworx/ape compile ``` -running the ape console: +**Docker Uninstall Process:** You will need to remove files generated by +docker + +```bash +sudo rm -rf **\~/.solcx** +sudo rm -rf **\~/.vvm** ``` -docker run -it \ ---volume $HOME/.ape:/root/.ape \ ---volume $HOME/.vvm:/root/.vvm \ ---volume $HOME/.solcx:/root/.solcx \ ---volume $PWD:/root/project \ ---workdir /root/project \ -apeworx/ape console + +## Overview + +For more in-depth information about the project please look at the [projects](~/userguides/project.md) +It explains the purpose of each folder and how to use them effectively. + +Use `ape init` to initialize your ape project folders. Visit [userguide project](~/userguide/project.md) for more information. + +```bash +ape init +``` + +## Environment Variables: + +Environment Variables are used to help connect you to your files or ecosystems outside of ApeWorX. + +Please setup environment variables (where applicable) and follow the latest instructions from the 3rd party: + +Example use case: + +```bash +# Used by the `ape-infura` plugin +export WEB3_INFURA_PROJECT_ID= +# Used by the `ape-alchemy` plugin +export WEB3_ALCHEMY_API_KEY= +``` + +Visit [ape-alchemy](https://github.com/ApeWorX/ape-alchemy/blob/main/README.md#quick-usage) + +Visit [ape-infura](https://github.com/ApeWorX/ape-infura#readme) + +# Ape Console + +Ape provides an IPython interactive console with useful pre-defined locals to interact with your project. +To interact with a deployed contract in a local environment, start by opening the console: + +```bash +ape console --network :mainnet-fork:hardhat ``` +Visit [Ape Console](https://docs.apeworx.io/ape/stable/commands/console.html) to learn how to use Ape Console. + ## Quick Usage -Ape is primarily meant to be used as a command line tool. Here are some things you can use ape to do: +Use `-h` to list all the commands. ```bash -# Work with your accounts -$ ape accounts list +ape -h +``` + +You can import or generate accounts. + +```bash +ape accounts import acc0 # Will prompt for a private key +ape accounts generate acc1 +```` + +List all your accounts with the `list` command. + +```bash +ape accounts list +``` + +Add any plugins you may need, such as `vyper`. + +```bash +ape plugins list -a +ape plugins install vyper +ape plugins list -a +``` + +**NOTE**: If a plugin does not originate from the +[ApeWorX GitHub organization](https://github.com/ApeWorX?q=ape&type=all), you will get a warning about installing +3rd-class plugins. Any plugin that is not an official plugin has the chance of not being trustworthy. Thus, you should +be mindful about which plugins you install. Additionally, plugins that come bundled with `ape` in the core installation +cannot be removed and are considered part of the `ape` core software. + +You can interact and compile contracts. +Here is an example of a project with a contract you interact with: + +```bash +git clone https://github.com/brownie-mix/vyper-token-mix.git +cd vyper-token-mix/ +``` + +You can compile contracts within the `contracts/` directory of your project. +The `--size` option will display you the size of the contract. + +```bash +ape compile --size +``` + +Provide the same arguments to `pytest` as you would to the `ape test` command. + +```bash +ape test -k test_only_one_thing --coverage +``` -# Compile your project's smart contracts -$ ape compile --size +Connect an IPython session through your favorite provider. -# Run your tests with pytest -$ ape test -k test_only_one_thing --coverage --gas +```bash +ape console --network ethereum:mainnet:infura +``` + +If you want to run specific files in a `scripts/` directory, you can do it using the `ape run` command. + +```bash +# This command will run a file named deploy in the scripts/ directory +$ ape run deploy +``` -# Connect an IPython session through your favorite provider -$ ape console --network ethereum:mainnet:infura +### Logging -# Add new plugins to ape -$ ape plugins install plugin-name +To enable debug logging, run your command with the `--verbosity` flag using `DEBUG` as the value: + +```bash +ape run --verbosity DEBUG ``` -Ape also works as a package. You can use the same networks, accounts, and projects from the ape package as you can in the cli: +You can use `ape` as a package outside of scripts for the `ape run` command as well. + +You can work with registered networks, providers, and blockchain ecosystems (like Ethereum): ```python -# Work with registered networks, providers, and blockchain ecosystems (like Ethereum) from ape import networks with networks.ethereum.mainnet.use_provider("infura"): ... # Work with the infura provider here +``` + +You can work with test accounts, local accounts, and (WIP) popular hardware wallets: -# Work with test accounts, local accounts, and (WIP) popular hardware wallets +```python from ape import accounts a = accounts[0] # Load by index -a = accounts.test_accounts[0] # Load test account by index a = accounts["example.eth"] # or load by ENS/address a = accounts.load("alias") # or load by alias +``` + +You can also work with contract types: -# Work with contract types +```python from ape import project c = a.deploy(project.MyContract, ...) c.viewThis() # Make Web3 calls c.doThat(sender=a) # Make Web3 transactions assert c.MyEvent[-1].caller == a # Search through Web3 events ``` - -## Development - -Please see the [contributing guide](CONTRIBUTING.md) to learn more how to contribute to this project. -Comments, questions, criticisms and pull requests are welcomed. - -## Documentation - -To build docs: - -```bash -python build_docs.py -``` - -## License - -This project is licensed under the [Apache 2.0](LICENSE). diff --git a/docs/index.md b/docs/index.md index b373cb729e..5d4ca1859b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,6 +11,8 @@ userguides/config userguides/transactions userguides/console + userguides/testing + ``` ```{eval-rst} diff --git a/docs/userguides/config.md b/docs/userguides/config.md index af02e5b655..a50b5826bd 100644 --- a/docs/userguides/config.md +++ b/docs/userguides/config.md @@ -157,4 +157,4 @@ Configure your test accounts: test: mnemonic: test test test test test test test test test test test junk number_of_accounts: 5 -``` +``` \ No newline at end of file diff --git a/docs/userguides/console.md b/docs/userguides/console.md index 2be679c835..918035318c 100644 --- a/docs/userguides/console.md +++ b/docs/userguides/console.md @@ -35,7 +35,7 @@ Out[2]: '0x68f768988e9bd4be971d527f72483f321975fa52aff9692b6d0e0af71fb77aaf' ### Init Function -If you include a function named `ape_init_extras`, it will be executed with the symbols from the existing namespace being provided as keyword arguments. This allows you to alter the scripts namespace using locals already included in the Ape namespace. If you return a `dict`, these values will be added to the console namespace. For example, you could setup an initialized Web3.py object by using one from an existing Ape Provider. +If you include a function named `ape_init_extras`, it will be executed with the symbols from the existing namespace being provided as keyword arguments. This allows you to alter the scripts namespace using locals already included in the Ape namespace. If you return a `dict`, these values will be added to the console namespace. For example, you could set up an initialized Web3.py object by using one from an existing Ape Provider. ```python def ape_init_extras(chain): diff --git a/docs/userguides/projects.md b/docs/userguides/projects.md index 9338afbe9a..4852b16e96 100644 --- a/docs/userguides/projects.md +++ b/docs/userguides/projects.md @@ -1,16 +1,20 @@ # Developing Projects with Ape -Use `ape` to create blockchain projects. A common project structure looks like this: +Use `ape init` to create your project. A common project structure looks like this: ``` -project # The root project directory -├── contracts/ # Project source files, such as '.sol' or '.vy' files -├── tests/ # Project tests, ran using the 'ape test' command -├── scripts/ # Project scripts, such as deploy scripts, ran using the 'ape run ' command -└── ape-config.yaml # The ape project configuration file +project # The root project directory +├── contracts/ # Project source files, such as '.sol' or '.vy' files + └── smart_contract_example.sol # Sample of a smart contract +├── tests/ # Project tests, ran using the 'ape test' command + └── test_sample.py # Sample of a test to run against your sample contract +├── scripts/ # Project scripts, such as deploy scripts, ran using the 'ape run <`name>' command + └── deploy.py # Sample script to automate a deployment of an ape project +└── ape-config.yaml # The ape project configuration file ``` -See the [Configuration guide](config.md) for a more detailed explanation of settings you can + + [Configuration guide](config.md) for a more detailed explanation of settings you can use in your `ape-config.yaml` files. ## Compiling Contracts @@ -23,7 +27,7 @@ from ape import project Your `project` contains all the "relevant" files, such as source files in the `contracts/` directory. The `contracts/` directory is where compilers look for contracts to compile. File extensions found within the `contracts/` -directory determine which compiler plugin `ape` uses. Make sure to install the compiler plugins you need if they are +directory determines which compiler plugin `ape` uses. Make sure to install the compiler plugins you need if they are missing by adding them to your `ape-config.yaml`'s `plugin` section, or manually adding via the following: ```bash @@ -100,6 +104,8 @@ ape console --network ::hardhat ## Scripts +The scripts folder contains project automation scripts, such as deploy scripts, as well as other executable jobs, such as scripts for running simulations. + You can write scripts that run using the `ape run` command. The `ape run` command will register and run Python files defined under the `scripts/` directory that do not start with an `_` underscore. If the scripts take advantage of utilities from our [`ape.cli`](../methoddocs/cli.html#ape-cli) submodule, @@ -114,137 +120,10 @@ installed, giving you more flexibility in how you define your scripts. ## Testing -You can test your project using the `ape test` command. The `ape test` command comes with the core-plugin `ape-test`. -The `ape-test` plugin extends the popular python testing framework -[pytest](https://docs.pytest.org/en/6.2.x/contents.html). - -### Test Structure - -Tests must be located in a project's `tests/` directory. Each test file must start with `test_` and have the `.py` -extension, such as `test_my_contract.py`. Each test method within the file must also start with `test_`. The following -is an example test: - -```python -def test_add(): - assert 1 + 1 == 2 -``` - -### Fixtures - -Fixtures are any type of re-usable instances of something with configurable scopes. `pytest` handles passing fixtures -into each test method as test-time. You can define your own fixtures or use existing ones. The `ape-test` plugin comes -with fixtures you will likely want to use: - -#### accounts fixture - -You have access to test accounts. These accounts are automatically funded, and you can use them to transact in your -tests. Access each [test account](../methoddocs/api.html?highlight=testaccount#ape.api.accounts.TestAccountAPI) by -index from the `accounts` fixture: - -```python -def test_my_method(accounts): - owner = accounts[0] - other = accounts[1] -``` - -For code readability and sustainability, create your own fixtures using the `accounts` fixture: - -```python -import pytest - - -@pytest.fixture -def owner(accounts): - return accounts[0] - - -@pytest.fixture -def other(accounts): - return accounts[1] - - -def test_my_method(owner, other): - ... -``` - -You can configure your accounts by changing the `mnemonic` or `number_of_accounts` settings in the `test` section of -your `ape-config.yaml` file: - -```yaml -test: - mnemonic: test test test test test test test test test test test junk - number_of_accounts: 5 -``` - -If you are using a fork-provider, such as [Hardhat](https://github.com/ApeWorX/ape-hardhat), you can use impersonated accounts by accessing random addresses off the fixture: - -```python -@pytest.fixture -def vitalik(accounts): - return accounts["0xab5801a7d398351b8be11c439e05c5b3259aec9b"] -``` - -#### project fixture - -You also have access to the `project` you are testing. You will need this to deploy your contracts in your tests. - -```python -import pytest - - -@pytest.fixture -def owner(accounts): - return accounts[0] - - -@pytest.fixture -def my_contract(project, owner): - # ^ use the 'project' fixture from the 'ape-test' plugin - return owner.deploy(project.MyContract) -``` - -### Test Pattern - -Tests are generally divisible into three parts: - -1. Set-up -2. Invocation -3. Assertion - -In the example above, we created a fixture that deploys our smart-contract. This is an example of a 'setup' phase. -Next, we need to call a method on our contract. Let's assume there is a method called `is_owner()` that returns `True` -when it is the owner of the contract making the transaction. - -This is an example of how that test may look: -```python -def test_is_owner(my_contract, owner, other): - owner_is_owner = my_contract.foo(sender=owner) - assert owner_is_owner - - other_is_owner = my_contract.foo(sender=other) - assert not other_is_owner -``` - -### Test Providers - -Out-of-the-box, your tests run using the `eth-tester` provider, which comes bundled with ape. If you have `geth` -installed, you can use the `ape-geth` plugin that also comes with ape. - -```bash -ape test --network ethereum:local:geth -``` +Use tests to verify your project. Testing is a complex topic, learn more about testing using Ape framework +[here](docs/userguides/testing.md) -Each testing plugin should work the same way. You will have access to the same test accounts. - -Another option for testing providers is the [ape-hardhat plugin](https://github.com/ApeWorX/ape-hardhat), which does -not come with `ape` but can be installed by including it in the `plugins` list in your `ape-config.yaml` file or -manually installing it using the command: - -```bash -ape plugins install hardhat -``` - -### Test Interactive - -Use ape test ``-I`` to open the interactive mode at the point of exception. This allows the user to inspect the point of failure in your tests. +You can test your project using the `ape test` command. The `ape test` command comes with the core-plugin `ape-test`. +The `ape-test` plugin extends the popular python testing framework +[pytest](https://docs.pytest.org/en/6.2.x/contents.html). \ No newline at end of file diff --git a/docs/userguides/quickstart.md b/docs/userguides/quickstart.md index 416e05d1b3..060259b6b7 100644 --- a/docs/userguides/quickstart.md +++ b/docs/userguides/quickstart.md @@ -1,203 +1,2 @@ -# Quick Start - -## Prerequisite - -In the latest release, Ape requires: - -- Linux or macOS -- Python 3.7.X or later - -**Windows**: - -1. Install Windows Subsystem Linux - [(WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) -2. Choose Ubuntu 20.04 OR Any other Linux Distribution with Python - 3.7.X or later - -Please make sure you are using Python 3.7.X or later. - -Check your python command by entering - -```bash -python3 --version -``` - -## Installation - -**Suggestion**: Create a virtual environment using `virtualenv` or `venv.` - -You may skip this creating a virtual environment if you know you don\'t -require one for your use case. - -* [virtualenv](https://pypi.org/project/virtualenv/) -* [venv](https://docs.python.org/3/library/venv.html) - -Create your virtual environment folder - -```bash -python3 -m venv /path/to/new/environment -source /bin/activate -``` - -You should see `(name_of_venv) DESKTOP_NAME:~/path:$`. -To deactivate the virtual environment, do: - -```bash -deactivate -``` - -Now that your Python version is later than 3.7.X and you have created a -virtual environment. Let\'s install Ape! There are 3 ways to install -ape: `pip`, `setuptools`, or `Docker`. - -### via `pip` - -You can install the latest release via -[pip](https://pypi.org/project/pip/): - -```bash -pip install -U pip -pip install eth-ape -``` - -### via `setuptools` - -You can clone the repository and use -[setuptools](https://github.com/pypa/setuptools) for the most up-to-date -version: - -```bash -git clone https://github.com/ApeWorX/ape.git -cd ape -python3 setup.py install -``` - -### via `docker` - -Please visit our -[Dockerhub](https://hub.docker.com/repository/docker/apeworx/ape) for -more details on using Ape with Docker. - -```bash -docker run \ ---volume $HOME/.ape:/root/.ape \ ---volume $HOME/.vvm:/root/.vvm \ ---volume $HOME/.solcx:/root/.solcx \ ---volume $PWD:/root/project \ ---workdir /root/project \ -apeworx/ape compile -``` - -**Docker Uninstall Process:** You will need to remove files generated by -docker - -```bash -sudo rm -rf **\~/.solcx** -sudo rm -rf **\~/.vvm** -``` - -## Quick Usage - -Use `-h` to list all the commands. - -```bash -ape -h -``` - -You can import or generate accounts. - -```bash -ape accounts import acc0 # Will prompt for a private key -ape accounts generate acc1 -```` - -List all your accounts with the `list` command. - -```bash -ape accounts list -``` - -Add any plugins you may need, such as `vyper`. - -```bash -ape plugins list -a -ape plugins install vyper -ape plugins list -a -``` - -**NOTE**: If a plugin does not originate from the -[ApeWorX GitHub organization](https://github.com/ApeWorX?q=ape&type=all), you will get a warning about installing -3rd-class plugins. Any plugin that is not an official plugin has the chance of not being trustworthy. Thus, you should -be mindful about which plugins you install. Additionally, plugins that come bundled with `ape` in the core installation -cannot be removed and are considered part of the `ape` core software. - -You can interact and compile contracts. -Here is an example of a project with a contract you interact with: - -```bash -git clone https://github.com/brownie-mix/vyper-token-mix.git -cd vyper-token-mix/ -``` - -You can compile contracts within the `contracts/` directory of your project. -The `--size` option will display you the size of the contract. - -```bash -ape compile --size -``` - -Provide the same arguments to `pytest` as you would to the `ape test` command. - -```bash -ape test -k test_only_one_thing --coverage -``` - -Connect an IPython session through your favorite provider. - -```bash -ape console --network ethereum:mainnet:infura -``` - -If you want to run specific files in a `scripts/` directory, you can do it with using the `ape run` command. - -```bash -# This command will run a file named deploy in the scripts/ directory -$ ape run deploy -``` - -### Logging - -To enable debug logging, run your command with the `--verbosity` flag using `DEBUG` as the value: - -```bash -ape run --verbosity DEBUG -``` - -You can use `ape` as a package outside of scripts for the `ape run` command as well. - -You can work with registered networks, providers, and blockchain ecosystems (like Ethereum): - -```python -from ape import networks -with networks.ethereum.mainnet.use_provider("infura"): - ... # Work with the infura provider here -``` - -You can work with test accounts, local accounts, and (WIP) popular hardware wallets: - -```python -from ape import accounts -a = accounts[0] # Load by index -a = accounts["example.eth"] # or load by ENS/address -a = accounts.load("alias") # or load by alias -``` - -You can also work with contract types: - -```python -from ape import project -c = a.deploy(project.MyContract, ...) -c.viewThis() # Make Web3 calls -c.doThat(sender=a) # Make Web3 transactions -assert c.MyEvent[-1].caller == a # Search through Web3 events -``` +```{include} ../../README.md +``` \ No newline at end of file diff --git a/docs/userguides/testing.md b/docs/userguides/testing.md new file mode 100644 index 0000000000..1e82beaf3a --- /dev/null +++ b/docs/userguides/testing.md @@ -0,0 +1,178 @@ +# Testing + +Testing an ape project is important and easy. + +## Test Structure + +Tests must be located in a project's `tests/` directory. Each **test file** must start with `test_` and have the `.py` +extension, such as `test_my_contract.py`. Each **test method** within the file must also start with `test_`. The following +is an example test: + +```python +def test_add(): + assert 1 + 1 == 2 +``` +## Test Pattern + +Tests are generally divisible into three parts: + +1. Set-up +2. Invocation +3. Assertion + +In the example above, we created a fixture that deploys our smart-contract. This is an example of a 'setup' phase. +Next, we need to call a method on our contract. Let's assume there is a method called `is_owner()` that returns `True` +when it is the owner of the contract making the transaction. + +This is an example of how that test may look: + +```python +def test_is_owner(my_contract, owner, other): + my_contract.set_owner(sender=owner) + assert owner == my_contract.owner() + + other_is_owner = my_contract.foo(sender=other) + assert not other_is_owner +``` + +## Fixtures + +Fixtures are any type of reusable instances of something with configurable scopes. `pytest` handles passing fixtures +into each test method as test-time. To learn more about [fixtures](https://docs.pytest.org/en/7.1.x/explanation/fixtures.html) + +Define fixtures for static data used by tests. This data can be accessed by all tests in the suite unless specified otherwise. This could be data as well as helpers of modules which will be passed to all tests. + +A common place to define fixtures are in the **conftest.py** which should be saved under the test directory: + +conftest.py is used to import external plugins or modules. By defining the following global variable, pytest will load the module and make it available for its test. + +You can define your own fixtures or use existing ones. The `ape-test` plugin comes +with fixtures you will likely want to use: + +### accounts fixture + +You have access to test accounts. These accounts are automatically funded, and you can use them to transact in your +tests. Access each [test account](../methoddocs/api.html?highlight=testaccount#ape.api.accounts.TestAccountAPI) by +index from the `accounts` fixture: + +```python +def test_my_method(accounts): + owner = accounts[0] + other = accounts[1] +``` + +For code readability and sustainability, create your own fixtures using the `accounts` fixture: + +```python +import pytest + + +@pytest.fixture +def owner(accounts): + return accounts[0] + + +@pytest.fixture +def other(accounts): + return accounts[1] + + +def test_my_method(owner, other): + ... +``` + +You can configure your accounts by changing the `mnemonic` or `number_of_accounts` settings in the `test` section of +your `ape-config.yaml` file: + +```yaml +test: + mnemonic: test test test test test test test test test test test junk + number_of_accounts: 5 +``` + +If you are using a fork-provider, such as [Hardhat](https://github.com/ApeWorX/ape-hardhat), you can use impersonated accounts by accessing random addresses off the fixture: + +```python +@pytest.fixture +def vitalik(accounts): + return accounts["0xab5801a7d398351b8be11c439e05c5b3259aec9b"] +``` + +### project fixture + +You also have access to the `project` you are testing. You will need this to deploy your contracts in your tests. + +```python +import pytest + + +@pytest.fixture +def owner(accounts): + return accounts[0] + + +@pytest.fixture +def my_contract(project, owner): + # ^ use the 'project' fixture from the 'ape-test' plugin + return owner.deploy(project.MyContract) +``` + +## Ape testing commands + +```bash +ape test +``` + +To run a particular test: + +```bash +ape test test_my_contract +``` + +Use ape test `-I` to open the interactive mode at the point of exception. This allows the user to inspect the point of failure in your tests. + +```bash +ape test test_my_contract -I -s +``` + +## Test Providers + +Out-of-the-box, your tests run using the `eth-tester` provider, which comes bundled with ape. If you have `geth` +installed, you can use the `ape-geth` plugin that also comes with ape. + +```bash +ape test --network ethereum:local:geth +``` + +Each testing plugin should work the same way. You will have access to the same test accounts. + +Another option for testing providers is the [ape-hardhat plugin](https://github.com/ApeWorX/ape-hardhat), which does +not come with `ape` but can be installed by including it in the `plugins` list in your `ape-config.yaml` file or +manually installing it using the command: + +```bash +ape plugins install hardhat +``` + +## Advanced Testing Tips + +If you want to use sample projects, follow this link to [Ape Academy](https://github.com/ApeAcademy). + +``` +project # The root project directory +└── tests/ # Project tests folder, ran using the 'ape test' command to run all tests within the folder. + └── conftest.py # A file to define global variable for testing + └── test_accounts.py # A test file, if you want to ONLY run one test file you can use 'ape test test_accounts.py' command + └── test_mint.py # A test file +``` +Here is a sample of test function from a sample [NFT](https://github.com/ApeAcademy/generative-nft) + +```python +def test_account_balance(owner, receiver, buyers, nft)): + # ^ use the 'project' fixture from the 'ape-test' plugin + quantity = 1 + nft.mint(quantity, ["0"], value=nft.PRICE() * quantity, sender=receiver) + actual = project.balanceOf(owner) + expect = quantity + assert actual == expect +``` diff --git a/docs/userguides/transactions.md b/docs/userguides/transactions.md index cab97c578e..803230d41f 100644 --- a/docs/userguides/transactions.md +++ b/docs/userguides/transactions.md @@ -20,11 +20,12 @@ def deploy(): account = accounts.load("MyAccount") return account.deploy(project.MyContract) ``` + ## Dynamic-Fee Transactions Before [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), all transactions used a `gas_price`. -After the London fork of Etheruem, the `gas_price` got broken up into two values, `max_fee` and `max_priority_fee`. +After the London fork of Ethereum, the `gas_price` got broken up into two values, `max_fee` and `max_priority_fee`. The `ape` framework supports both types of transactions. By default, transactions use the dynamic-fee model. Making contract calls without specifying any additional `kwargs` will use a dynamic-fee transaction.