Test API¶
The test
package contains classes and methods for running tests and evaluating test coverage.
This functionality is typically accessed via pytest. See Unit Testing with Pytest.
brownie.test.fixtures
¶
The fixtures
module contains custom fixtures provided by the Brownie Pytest plugin.
Pytest Fixtures¶
Note
These fixtures are only available when pytest
is run from inside a Brownie project folder.
Session Fixtures¶
These fixtures provide access to objects related to the project being tested.
-
fixtures.
a
¶ Session scope. Short form of the
accounts
fixture.
Isolation Fixtures¶
These fixtures are used to effectively isolate tests. If included on every test within a module, that module may now be skipped via the --update
flag when none of the related files have changed since it was last run.
-
fixtures.
module_isolation
¶ Module scope. When used, this fixture is always applied before any other module-scoped fixtures.
Resets the local environment before starting the first test and again after completing the final test.
-
fixtures.
fn_isolation
(module_isolation)¶ Function scope. When used, this fixture is always applied before any other function-scoped fixtures.
Applies the
module_isolation
fixture, and additionally takes a snapshot prior to running each test which is then reverted to after the test completes. The snapshot is taken immediately after any module-scoped fixtures are applied, and before all function-scoped ones.
Coverage Fixtures¶
These fixtures alter the behaviour of tests when coverage evaluation is active.
-
fixtures.
no_call_coverage
¶ Function scope. Coverage evaluation will not be performed on called contact methods during this test.
-
fixtures.
skip_coverage
¶ Function scope. If coverage evaluation is active, this test will be skipped.
brownie.test.plugin
¶
The plugin
module is the entry point for the Brownie pytest plugin. It contains two pytest
hook point methods that are used for setting up the plugin. The majority of the plugin functionality is handled by a plugin manager which is instantiated in the pytest_configure
method.
brownie.test.manager
¶
The manager
module contains Brownie classes used internally to manage the Brownie pytest plugin.
Plugin Managers¶
One of these classes is instantiated in the pytest_configure
method of brownie.test.plugin
. Which is used depends on whether or not pytest-xdist is active.
-
class
manager.base.
PytestBrownieBase
¶ Base class that is inherited by all Brownie plugin managers.
-
class
manager.runner.
PytestBrownieRunner
¶ Runner plugin manager, used when
xdist
is not active.
-
class
manager.runner.
PytestBrownieXdistRunner
¶ xdist
runner plugin manager. Inherits fromPytestBrownieRunner
.
-
class
manager.master.
PytestBrownieMaster
¶ xdist
master plugin manager.
RevertContextManager¶
The RevertContextManager
closely mimics the behaviour of pytest.raises.
-
class
plugin.
RevertContextManager
(revert_msg=None)¶ Context manager used to handle
VirtualMachineError
exceptions. RaisesAssertionError
if no transaction has reverted when the context closes.revert_msg
: Optional. Raises anAssertionError
if the transaction does not revert with this error string.
This class is available as
brownie.reverts
whenpytest
is active.1 2 3 4 5 6
import brownie def test_transfer_reverts(Token, accounts): token = accounts[0].deploy(Token, "Test Token", "TST", 18, "1000 ether") with brownie.reverts(): token.transfer(account[2], "10000 ether", {'from': accounts[1]})
brownie.test.output
¶
The output
module contains methods for formatting and displaying test output.
Internal Methods¶
-
output.
_save_coverage_report
(build, coverage_eval, report_path)¶ Generates and saves a test coverage report for viewing in the GUI.
build
: Project Build objectcoverage_eval
: Coverage evaluation dictreport_path
: Path to save to. If the path is a folder, the report is saved ascoverage.json
.
-
output.
_print_gas_profile
()¶ Formats and prints a gas profile report.
-
output.
_print_coverage_totals
(build, coverage_eval)¶ Formats and prints a coverage evaluation report.
build
: Project Build objectcoverage_eval
: Coverage evaluation dict
-
output.
_get_totals
(build, coverage_eval)¶ Generates an aggregated coverage evaluation dict that holds counts and totals for each contract function.
build
: Project Build objectcoverage_eval
: Coverage evaluation dict
Returns:
{ "ContractName": { "statements": { "path/to/file": { "ContractName.functionName": (count, total), .. }, .. }, "branches" { "path/to/file": { "ContractName.functionName": (true_count, false_count, total), .. }, .. } }
-
output.
_split_by_fn
(build, coverage_eval)¶ Splits a coverage eval dict so that coverage indexes are stored by contract function. The returned dict is no longer compatible with other methods in this module.
build
: Project Build objectcoverage_eval
: Coverage evaluation dict- Original format:
{"path/to/file": [index, ..], .. }
- Returned format:
{"path/to/file": { "ContractName.functionName": [index, .. ], .. }
-
output.
_get_highlights
(build, coverage_eval)¶ Returns a highlight map formatted for display in the GUI.
build
: Project Build objectcoverage_eval
: Coverage evaluation dict
Returns:
{ "statements": { "ContractName": {"path/to/file": [start, stop, color, msg], .. }, }, "branches": { "ContractName": {"path/to/file": [start, stop, color, msg], .. }, } }
See the Viewing Security Report Data for more info on the return format.
brownie.test.coverage
¶
The coverage
module is used storing and accessing coverage evaluation data.
Module Methods¶
-
coverage.
get_coverage_eval
()¶ Returns all coverage data, active and cached.
-
coverage.
get_merged_coverage_eval
()¶ Merges and returns all active coverage data as a single dict.
-
coverage.
clear
()¶ Clears all coverage eval data.
Internal Methods¶
-
coverage.
add_transaction
(txhash, coverage_eval)¶ Adds coverage eval data.
-
coverage.
add_cached_transaction
(txhash, coverage_eval)¶ Adds coverage data to the cache.
-
coverage.
check_cached
(txhash, active=True)¶ Checks if a transaction hash is present within the cache, and if yes includes it in the active data.
-
coverage.
get_active_txlist
()¶ Returns a list of coverage hashes that are currently marked as active.
-
coverage.
clear_active_txlist
()¶ Clears the active coverage hash list.