Check Runtime
Describes the try-runtime command-line tool for testing a specified runtime state against a production snapshot of chain state.
Last updated
Describes the try-runtime command-line tool for testing a specified runtime state against a production snapshot of chain state.
Last updated
The try-runtime command-line tool enables you to query a snapshot of runtime storage using an data structure to store state. By using the in-memory storage, you can write tests for a specified runtime state so that you can test against real chain state before going to production.
In its simplest form, you can use try-runtime to test the runtime state by doing the following:
Connect to a remote node.
Call a specific runtime API.
Retrieve state from the node at a specific block.
Write tests for the data retrieved.
The initial motivation for try-runtime came from the need to test runtime changes against state from a real chain. Prior and existed for writing unit and integrated tests with mock data, but lacked the ability to test against a chain's actual state. The try-runtime tool extends TestExternalities and BasicExternalities by retrieving state using the following RPC endpoints for the node:
rpc_get_storage
rpc_get_keys_paged
(see for more details.)
After using the key-value database to retrieve state, try-runtime inserts the data into TestExternalities.
The try-runtime tool has its own implementation of externalities called which is just a wrapper around TestExternalities that uses a generic where data is .
The diagram below illustrates the way externalities sits outside a compiled runtime as a means to capture the storage of that runtime.
With remote_externalities, you can capture some chain state and run tests on it. Essentially, RemoteExternalities will populate a TestExternalities with a real chain's data.
The most common use case for try-runtime is to help you prepare for storage migration and runtime upgrades.
Because the RPC calls that query storage are computationally expensive, there are a number of command-line options you should set for a running node before you use the try-runtime command. To prepare a node for try-runtime testing, set the following options:
Set --rpc-max-payload 1000 to ensure large RPC queries can work.
Set --rpc-cors all to ensure WebSocket connections can come through.
By default, runtime upgrade hooks—which can be defined inside of the runtime or inside pallets—specify what should happen when there's been a runtime upgrade. That is, the default on_runtime_upgrade method only describes runtime state after the upgrade. However, it is possible to use methods provided by try-runtime to inspect and compare the runtime state before and after a runtime upgrade for testing purposes.
If you enable the try-runtime feature for the runtime, you can define pre-upgrade and post-upgrade hooks for the runtime as follows:
With these function, you can use the pre_upgrade hook to retrieve the runtime state and return it as a Vec result. You can the pass the Vec as input parameter to the post_upgrade hook.
To use try-runtime from the command-line, run your node with the --features=try-runtime flag.
For example:
You can use the following subcommands with try-runtime:
on-runtime-upgrade: Executes tryRuntime_on_runtime_upgrade against the given runtime state.
offchain-worker: Executes offchainWorkerApi_offchain_worker against the given runtime state.
execute-block: Executes core_execute_block using the given block and the runtime state of the parent block.
follow-chain: Follows a given chain's finalized blocks and applies to all its extrinsics. This allows the behavior of a new runtime to be inspected over a long period of time, with real transactions coming as input.
To view usage information for a specific try-runtime subcommand, specify the subcommand and the --help flag. For example, to see usage information for try-runtime on-runtime-upgrade, you can run the following command:
For example, you can run try-runtime with the on-runtime-upgrade subcommand for a chain running locally with a command like this:
You can use try-runtime to re-execute code from the ElectionProviderMultiPhase offchain worker on localhost:9944 with a command like this:
You can run the migrations of the local runtime on the state of SomeChain with a command like this:
You can run try-runtime against the state for a specific block number with a command like this:
Notice that this command requires the --no-spec-name-check command-line option.
To query state, try-runtime uses the RPC methods provided by . In particular:
This method returns the storage value for the key that represents the block you specify.
This method returns the keys that match a prefix you specify with pagination support.
You can combine try-runtime with to test your chain before production. Use try-runtime to test your chain's migration and its pre and post states. Then, use fork-off-substrate if you want to check that block production continues after the migration.
