From ab38c7a944f23b1a9bf306851fcdb0cecb1bab3d Mon Sep 17 00:00:00 2001 From: Joel Dudley Date: Tue, 10 Jul 2018 15:17:59 +0100 Subject: [PATCH] Consolidates and extends debugging information. (#3548) * Consolidates and extends debugging information. * Clearer remote debugging instructions. --- docs/source/building-a-cordapp-index.rst | 1 + docs/source/debugging-a-cordapp.rst | 73 ++++++++++++++++++++++++ docs/source/running-a-node.rst | 6 +- docs/source/tutorial-cordapp.rst | 36 +++--------- 4 files changed, 86 insertions(+), 30 deletions(-) create mode 100644 docs/source/debugging-a-cordapp.rst diff --git a/docs/source/building-a-cordapp-index.rst b/docs/source/building-a-cordapp-index.rst index 9539ac5b31..925d1cc535 100644 --- a/docs/source/building-a-cordapp-index.rst +++ b/docs/source/building-a-cordapp-index.rst @@ -6,6 +6,7 @@ CorDapps cordapp-overview writing-a-cordapp + debugging-a-cordapp upgrade-notes upgrading-cordapps cordapp-build-systems diff --git a/docs/source/debugging-a-cordapp.rst b/docs/source/debugging-a-cordapp.rst new file mode 100644 index 0000000000..a3dab57304 --- /dev/null +++ b/docs/source/debugging-a-cordapp.rst @@ -0,0 +1,73 @@ +Debugging a CorDapp +=================== + +.. contents:: + +There are several ways to debug your CorDapp. + +Using a ``MockNetwork`` +----------------------- + +You can attach the `IntelliJ IDEA debugger `_ to a +``MockNetwork`` to debug your CorDapp: + +* Define your flow tests as per :doc:`api-testing` + + * In your ``MockNetwork``, ensure that ``threadPerNode`` is set to ``false`` + +* Set your breakpoints +* Run the flow tests using the debugger. When the tests hit a breakpoint, execution will pause + +Using the node driver +--------------------- + +You can also attach the `IntelliJ IDEA debugger `_ to nodes +running via the node driver to debug your CorDapp. + +With the nodes in-process +^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Define a network using the node driver as per :doc:`tutorial-integration-testing` + + * In your ``DriverParameters``, ensure that ``startNodesInProcess`` is set to ``true`` + +2. Run the driver using the debugger + +3. Set your breakpoints + +4. Interact with your nodes. When execution hits a breakpoint, execution will pause + + * The nodes' webservers always run in a separate process, and cannot be attached to by the debugger + +With remote debugging +^^^^^^^^^^^^^^^^^^^^^ + +1. Define a network using the node driver as per :doc:`tutorial-integration-testing` + + * In your ``DriverParameters``, ensure that ``startNodesInProcess`` is set to ``false`` and ``isDebug`` is set to + ``true`` + +2. Run the driver. The remote debug ports for each node will be automatically generated and printed to the terminal. + For example: + +.. sourcecode:: none + + [INFO ] 11:39:55,471 [driver-pool-thread-0] (DriverDSLImpl.kt:814) internal.DriverDSLImpl.startOutOfProcessNode - + Starting out-of-process Node PartyA, debug port is 5008, jolokia monitoring port is not enabled {} + +3. Attach the debugger to the node of interest on its debug port: + + * In IntelliJ IDEA, create a new run/debug configuration of type ``Remote`` + * Set the run/debug configuration's ``Port`` to the debug port + * Start the run/debug configuration in debug mode + +4. Set your breakpoints + +5. Interact with your node. When execution hits a breakpoint, execution will pause + + * The nodes' webservers always run in a separate process, and cannot be attached to by the debugger + +By enabling remote debugging on a node +-------------------------------------- + +See :ref:`enabling-remote-debugging`. \ No newline at end of file diff --git a/docs/source/running-a-node.rst b/docs/source/running-a-node.rst index 6653275520..14c6f91268 100644 --- a/docs/source/running-a-node.rst +++ b/docs/source/running-a-node.rst @@ -64,13 +64,15 @@ The node can optionally be started with the following command-line options: * ``--sshd``: Enables SSHD server for node administration * ``--version``: Print the version and exit +.. _enabling-remote-debugging: + Enabling remote debugging ~~~~~~~~~~~~~~~~~~~~~~~~~ -To enable remote debugging of the node, run the following from the terminal window: +To enable remote debugging of the node, run the node with the following JVM arguments: ``java -Dcapsule.jvm.args="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" -jar corda.jar`` -This command line will start the debugger on port 5005 and pause the process awaiting debugger attachment. +This will allow you to attach a debugger to your node on port 5005. Starting all nodes at once on a local machine from the command line ------------------------------------------------------------------- diff --git a/docs/source/tutorial-cordapp.rst b/docs/source/tutorial-cordapp.rst index eba4a85348..e87aadc607 100644 --- a/docs/source/tutorial-cordapp.rst +++ b/docs/source/tutorial-cordapp.rst @@ -444,44 +444,24 @@ The nodes can be configured to communicate as a network even when distributed ac value after the nodes have been moved to their individual machines. The initial bootstrapping process requires access to the nodes' databases and if two nodes share the same H2 port, the process will fail. -Testing and debugging ---------------------- +Testing your CorDapp +-------------------- -Testing a CorDapp -~~~~~~~~~~~~~~~~~ Corda provides several frameworks for writing unit and integration tests for CorDapps. Contract tests -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ You can run the CorDapp's contract tests by running the ``Run Contract Tests - Kotlin`` run configuration. Flow tests -^^^^^^^^^^ +~~~~~~~~~~ You can run the CorDapp's flow tests by running the ``Run Flow Tests - Kotlin`` run configuration. Integration tests -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ You can run the CorDapp's integration tests by running the ``Run Integration Tests - Kotlin`` run configuration. -Debugging Corda nodes -~~~~~~~~~~~~~~~~~~~~~ -Debugging is done via IntelliJ as follows: +Debugging your CorDapp +---------------------- -1. Start the nodes using the “Run Example CorDapp” run configuration in IntelliJ - -2. IntelliJ will build and run the CorDapp. The remote debug ports for each node will be automatically generated and - printed to the terminal. For example: - -.. sourcecode:: none - - [INFO ] 15:27:59.533 [main] Node.logStartupInfo - Working Directory: /Users/joeldudley/cordapp-example/build/20170707142746/PartyA - [INFO ] 15:27:59.533 [main] Node.logStartupInfo - Debug port: dt_socket:5007 - -3. Edit the “Debug CorDapp” run configuration with the port of the node you wish to connect to - -4. Run the “Debug CorDapp” run configuration - -5. Set your breakpoints and interact with the node you've connected to. When the node hits a breakpoint, execution will - pause - - * The node webserver runs in a separate process, and is not attached to by the debugger +See :doc:`debugging-a-cordapp`.