diff --git a/docs/source/upgrading-cordapps.rst b/docs/source/upgrading-cordapps.rst index 6b28ec1fd9..5e519a20d3 100644 --- a/docs/source/upgrading-cordapps.rst +++ b/docs/source/upgrading-cordapps.rst @@ -641,3 +641,29 @@ Although not strictly related to versioning, AMQP serialisation dictates that we wildcard * Any superclass must adhere to the same rules, but can be abstract * Object graph cycles are not supported, so an object cannot refer to itself, directly or indirectly + + +Testing CorDapp upgrades +------------------------ + +At the time of this writing there is no platform support to test CorDapp upgrades. There are plans to add support in a future version. +This means that it is not possible to write automated tests using just the provided tooling. + +To test an implicit upgrade, you must simulate a network that initially has only nodes with the old version of the CorDapp, and then nodes gradually transition to the new version. +Typically, in such a complex upgrade scenario, there must be a deadline by which time all nodes that want to continue to use the CorDapp must upgrade. +To achieve this, this deadline must be configured in the flow logic which must only use new features afterwards. + +This can be simulated with a scenario like this: + +1. Write and individually test the new version of the state and contract. +2. Setup a network of nodes with the previous version. In the simplest form, `deployNodes` can be used for this purpose. +3. Run some transactions between nodes. +4. Upgrade a couple of nodes to the new version of the CorDapp. +5. Continue running transactions between various combinations of versions. Also make sure transactions that were created between nodes with the new version +are being successfully read by nodes with the old CorDapp. +6. Upgrade all nodes and simulate the deadline expiration. +7. Make sure old transactions can be consumed, and new features are successfully used in new transactions. + + + +