f0138dfe17
* Moves code sections in tutorials to code files. * Removes wallet references. * Updates repo layout doc. * Removes remaining cordapp-tutorial references, replaced with cordapp-example. * Fixes broken link. * Misc docs fixes. * Refreshes the ServiceHub and rpc ops api pages. * Updates the cheat sheet. * Updates cookbooks. * Refreshes the running-a-notary tutorial. * Updates flow-testing tutorial * Updates tear-offs tutorial. * Refreshes integration-testing tutorial. * Updates to contract tutorial and accompanying code to bring inline with V1 release. * Refreshes contract-upgrade tutorial. * Fixed broken code sample in "writing a contract" and updated contracts dsl. * Added contract ref to java code. Fixed broken rst markup. * Updates transaction-building tutorial. * Updates the client-rpc and flow-state-machines tutorials. * Updates the oracles tutorial. * Amended country in X500 names from "UK" to "GB" * Update FlowCookbook.kt * Amended cheatsheet. Minor update on contract upgrades tutoraial. * Added `extraCordappPackagesToScan` to node driver. * Changes to match new function signature. * Update to reflect change in location of cash contract name.
4.8 KiB
Integration testing
Integration testing involves bringing up nodes locally and testing invariants about them by starting flows and inspecting their state.
In this tutorial we will bring up three nodes - Alice, Bob and a notary. Alice will issue cash to Bob, then Bob will send this cash back to Alice. We will see how to test some simple deterministic and nondeterministic invariants in the meantime.
Note
This example where Alice is self-issuing cash is purely for demonstration purposes, in reality, cash would be issued by a bank and subsequently passed around.
In order to spawn nodes we will use the Driver DSL. This DSL allows one to start up node processes from code. It manages a network map service and safe shutting down of nodes in the background.
example-code/src/integration-test/kotlin/net/corda/docs/IntegrationTestingTutorial.kt
The above code starts three nodes:
- Alice, who has user permissions to start the
CashIssueFlowandCashPaymentFlowflows - Bob, who only has user permissions to start the
CashPaymentFlow - A notary that offers a
ValidatingNotaryService. We won't connect to the notary directly, so there's no need to provide aUser
The startNode function returns a future that completes once the node is fully started. This allows starting of the nodes to be parallel. We wait on these futures as we need the information returned; their respective NodeHandles s.
example-code/src/integration-test/kotlin/net/corda/docs/IntegrationTestingTutorial.kt
After getting the handles we wait for both parties to register with the network map to ensure we don't have race conditions with network map registration. Next we connect to Alice and Bob respectively from the test process using the test user we created. Then we establish RPC links that allow us to start flows and query state.
example-code/src/integration-test/kotlin/net/corda/docs/IntegrationTestingTutorial.kt
We will be interested in changes to Alice's and Bob's vault, so we query a stream of vault updates from each.
Now that we're all set up we can finally get some cash action going!
example-code/src/integration-test/kotlin/net/corda/docs/IntegrationTestingTutorial.kt
The first loop creates 10 threads, each starting a CashFlow flow on the Alice node. We specify that we want to issue i dollars to Bob, setting our notary as the notary responsible for notarising the created states. Note that no notarisation will occur yet as we're not spending any states, only creating new ones on the ledger.
We started the flows from different threads for the sake of the tutorial, to demonstrate how to test non-determinism, which is what the expectEvents block does.
The Expect DSL allows ordering constraints to be checked on a stream of events. The above code specifies that we are expecting 10 updates to be emitted on the bobVaultUpdates stream in unspecified order (this is what the parallel construct does). We specify an (otherwise optional) match predicate to identify specific updates we are interested in, which we then print.
If we run the code written so far we should see 4 nodes starting up (Alice, Bob, the notary and an implicit Network Map service), then 10 logs of Bob receiving 1,2,...10 dollars from Alice in some unspecified order.
Next we want Bob to send this cash back to Alice.
example-code/src/integration-test/kotlin/net/corda/docs/IntegrationTestingTutorial.kt
This time we'll do it sequentially. We make Bob pay 1,2,..10 dollars to Alice in order. We make sure that a the CashFlow has finished by waiting on startFlow 's returnValue.
Then we use the Expect DSL again, this time using sequence to test for the updates arriving in the order we expect them to.
Note that parallel and sequence may be nested into each other arbitrarily to test more complex scenarios.
That's it! We saw how to start up several corda nodes locally, how to connect to them, and how to test some simple invariants about CashFlow.
To run the complete test you can open example-code/src/integration-test/kotlin/net/corda/docs/IntegrationTestingTutorial.kt from IntelliJ and run the test, or alternatively use gradle:
# Run example-code integration tests
./gradlew docs/source/example-code:integrationTest -i