Quick Start

• Install Docker Engine or Docker Desktop
• Run basic acceptance tests against a new Quorum network using Raft consensus:

  docker run --rm --network host -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/acctests:/tmp/acctests \
          quorumengineering/acctests:latest test -Pauto -Dtags="basic || networks/typical::raft" \
          -Dauto.outputDir=/tmp/acctests -Dnetwork.forceDestroy=true
  

Development

Development environment requires the following:

• JDK 11+
• Maven 3.6.x
• Solidity Compiler (make sure solc is installed and not solcjs)
  • For MacOS: use brew
  • For Linux: use apt, snap or emerge
  • For Windows: download from here
• Gauge

With built-in provisioning feature:

• Docker Engine or Docker Desktop
• Terraform 0.12.x
• Terraform Provider Quorum
  • Refer to this guide on how to install the provider manually

For more details on tools and versions being used, please refer to Dockerfile

Writing Tests

• Using Gauge test automation framework
• Test Specs are stored in src/specs folder
  • Folder 01_basic contains specifications which describe Quorum's basic functionalities. All specifications must be tagged as basic
  • Folder 02_advanced contains specifications which are for making sure Quorum's basic functionalities are working under different conditions in the chain. All specifications must be tagged as advanced
• Glue codes are written in Java under src/test/java folder
• Tests are generally written against 4-node Quorum network

Running Tests

With auto-provisioning network

💡 Tag networks/typical::raft means:

• Executing tests which are tagged with the value
• Instructing Maven to provision networks/typical with profile raft when using Maven Profile auto (i.e.: -Pauto)
• networks/typical is a folder that contains Terraform configuration to provision the network

• Run basic tests for raft consensus:

  mvn clean test -Pauto -Dtags="basic || basic-raft || networks/typical::raft"
  

• Run basic tests for istanbul consensus:

  mvn clean test -Pauto -Dtags="basic || basic-istanbul || networks/typical::istanbul"
  

• Force destroy the network after running tests:

  mvn clean test -Pauto -Dtags="basic || basic-raft || networks/typical::raft" -Dnetwork.forceDestroy=true
  

• Start the network without running tests:

  mvn process-test-resources -Pauto -Dnetwork.target="networks/typical::raft"
  

• Destroy the network:

  mvn exec:exec@network.terraform-destroy -Pauto -Dnetwork.folder="networks/typical" -Dnetwork.profile=raft
  

Below is the summary of various parameters:

Parameters	Description
-Dnetwork.target="<folder>::<profile"	Shorthand to specify the Terraform folder and profile being used to create Quorum Network
-Dnetwork.folder="<folder>"	Terraform folder being used to create Quorum Network
-Dnetwork.profile="<profile>"	Terraform workspace and terraform.<profile>.tfvars being used
-Dnetwork.forceDestroy="true" or "false"	Destroy the Quorum Network after test completed. Default is false
-Dnetwork.skipApply="true" or "false"	Don't create Quorum Network. Default is false
-Dnetwork.skipWait="true" or "false"	Don't perform health check and wait for Quorum Network. Default is false
-Dinfra.target="<folder>::<profile"	Shorthand to specify the Terraform folder and profile being used to create an infrastructure to host Docker Engine
-Dinfra.folder="<folder>"	Terraform folder being used to create the infrastructure
-Dinfra.profile="<profile>"	Terraform workspace and terraform.<profile>.tfvars being used
-Dinfra.forceDestroy="true" or "false"	Destroy the infrastructure after test completed. Default is false
-Dinfra.skipApply="true" or "false"	Don't create the infrastructure. Default is false
-Dinfra.skipWait="true" or "false"	Don't perform health check and wait for Quorum Network. Default is false

With existing quorum-examples network

SPRING_PROFILES_ACTIVE=local.7nodes mvn clean test -Dtags="basic || basic-raft || networks/typical::raft"

Remote Docker

ℹ️ Because Docker Java SDK doesn't support SSH transport hence we need to open TCP endpoint.

networks/_infra/aws-ec2 provides Terraform configuration in order to spin off an EC2 instance with remote Docker API support.

E.g.: To start networks/typical with remote Docker infrastructure:

• Make sure you have the right AWS credentials in your environment
• Run:

  mvn process-test-resources -Pauto -Dnetwork.target="networks/typical::raft" -Dinfra.target="networks/_infra/aws-ec2::us-east-1"
  

Logging

• Set environment variable: LOGGING_LEVEL_COM_QUORUM_GAUGE=DEBUG

---