The Recon Invariant Testing Extension
Tools for faster invariant testing directly in your code editor
Introduction
The Recon for Visual Studio Code allows you to use Recon's suite of tools directly in your code editor. These tools are designed to make setting up and running an invariant testing suite faster and simpler.
With the extension you can:
Scaffold your invariant testing suite
Quickly create handlers for each function you’re targeting
Auto-generate mock contracts
Generate a report after running Echidna/Medusa on your suite
Generate a condensed coverage report
Generate reproducer unit tests for debugging broken properties
After installing the extension from the Visual Studio Code marketplace, your Foundry project will automatically be compiled when opened in a new window in your code editor.
Scaffold Your Target Functions
After building your project, you can choose which of your contract functions you want to add target functions for using the CONTRACTS section in the sidebar.
Once you've selected the contract functions you'd like to add to your scaffolding, the extension will generate a Chimera Framework template for your project.
This will install the Chimera dependency, generate the necessary fuzzer config files, and generate all the necessary test files for your project using the Create Chimera App template.
For more on how to use the Chimera Framework, check out the Chimera Framework section.
Function Handlers
Testing Modes
When selecting which contract functions you'd like to target, you can select from three “testing modes” to help define how you'd like to test your target functions:
Normal Mode - This just adds a handler function as a wrapper around the underlying target function.
Fail Mode - This will add a handler function that includes an assertion at the end of the call to the target function. You can replace this assertion with any other assertion you'd like to test.
Catch Mode - This will add a handler function that includes a try catch block around the call to the target function. You can add any custom logic to the catch block such as an assertion about when a function should or shouldn't revert.
Actor Mode
In our second version of Create Chimera App we introduced the idea of an ActorManager which allows you to track all simulated users in the system from one contract which gets inherited in your setup.
We’ve embedded this idea into the extension and now you can use the actor modes to specify which actor should be calling a given target function:
Actor - This uses the currently set actor returned by `_getActor()` to prank and call the target function.
Admin - This uses the admin role to call the target function (this is defaulted to `address(this)`).
Auto Mocking
When setting up a test suite it’s pretty common that the you’ll have core system contracts whose behavior you intend to test and periphery contracts that need to be deployed in order for the core contracts to work but whose behavior is irrelevant to what you’re trying to test. In this case mocking the periphery contracts is often the best choice so as to not have to deploy the actual implementation and any of its subsequent dependencies with all their required configurations.
Mocking is generally simple but annoying to do because you need to determine when you need to return values and when you can just have a function do nothing.
The Recon extension allows you to auto-mock specific contracts needed for your setup using the ABI to Mock tool. This will generate a mock of any system contracts based on the contract's parameters and return values.
Report Generation
After running your suite with Echidna or Medusa a report is automatically generated which shows all the properties tested in your fuzzing run and whether they passed or failed.
You can open the report in the COVERAGE REPORT section in the sidebar by clicking the checklist icon:
Condensed Coverage Report
By default Echidna and Medusa generate coverage reports that include all files that were built during compilation. This results in a very large HTML file that can be difficult to manually parse through to check if certain lines are being covered in the early stages of building a suite.
You can view a condensed version of the coverage report which removes contracts that aren't touched by the fuzzer by clicking the open in new tab button in the COVERAGE REPORTS section.
Reproducer Generation
When Echidna/Medusa break a property, they output a call trace that allows you to reproduce the calls made to break the property. This call trace is difficult to read and impractical for debugging so it’s best to turn this into a Foundry unit test so you can more easily identify the source of the broken property.
We’ve built this into the extension so that if a property breaks, the extension will automatically generate a Foundry unit test reproducer for the property.
Clicking yes will add the reproducer to the CryticToFoundry contract that's created when you generate a Chimera template.
Conclusion
The Recon extension was built to make invariant testing easier. With it, repetitive and manual tasks can be easily accomplished in a few clicks.
We’ve seen how using the extension we can:
Add all the necessary scaffolding for an invariant suite using the Chimera framework
Generate handler functions with different “testing modes” and actors calling them
Auto-generate mock contracts for faster setup
Generate a report after running Echidna/Medusa to share your test results
Generate a condensed coverage report for easier searching
Generate reproducer unit tests for debugging broken properties
To view the full guide for using the extension, checkout the Recon book.
Prefer to have someone else handle your invariant testing?
At Recon we offer boutique audits powered by invariant testing. With this you get the best of both worlds, a security audit done by an elite researcher paired with a cutting edge invariant testing suite.
Sound interesting? Reach out to us here:
