PolySwarmPolySwarmPolySwarmPolySwarm
Help

Integration Testing

Overview

The PolySwarm marketplace is composed of a myriad of participants and technologies: Ethereum & IPFS nodes, contracts, microengines, ambassadors, arbiters, artifacts and much more. Testing a single component often demands availability of all of the other components.

The orchestration project makes standing up a complete testnet easy and seamless. True to its name, orchestration orchestrates all the components necessary to stand up and tear down an entire PolySwarm marketplace environment on a local development machine.

Always ensure that you have the latest updates to core PolySwarm Docker images prior to running integration tests. docker-compose ... up commands must always be proceeded with docker-compose ... pull commands.

Arbiter testing is not yet supported.

Windows developers: unless otherwise specified, execute all commands on this page in your Linux VM.


Getting Started

Clone orchestration adjacent to your participant directory:

$ git clone https://github.com/polyswarm/orchestration

The following docker-compose files in the orchestration repository will help with testing:

  • base.yml: defines the infrastructure basics for our testnet (e.g. geth nodes and relays)
  • ambassador-eicar.yml: defines an ambassador service using eicar.py
  • arbiter-verbatim.yml: defines an arbiter service using verbatim.py
  • microengine-eicar.yml: defines a microengine service using eicar.py
  • microengine-clamav.yml: defines a microengine service using clamav.py + the ClamAV daemon
  • microengine-multi.yml: defines a microengine service using multi.py

Create the orchestration_default network:

$ docker network create orchestration_default

(Optional) Preview a Complete, Working Testnet

In the cloned orchestration directory:

$ docker-compose -f base.yml -f ambassador-eicar.yml -f microengine-eicar.yml -f arbiter-verbatim.yml pull
$ docker-compose -f base.yml -f ambassador-eicar.yml -f microengine-eicar.yml -f arbiter-verbatim.yml up

You'll see output from the following services:

  1. contractor: Responsible for housing & deploying the PolySwarm Nectar (NCT) and BountyRegistry contracts onto our development testnet.
  2. polyswarmd: The PolySwarm daemon providing convenient access to the services offered by homechain, sidechain and ipfs. All participants (ambassador(s), arbiter(s) and microengine(s)) speak to this service.
  3. consul: A key-value store use by contractor to communicate crucial information to polyswarmd, e.g. the Ethereum address of the deployed BountyRegistry contract.
  4. homechain: A geth node running our testnet's "homechain". See Homechains & Sidechains for an explanation of our split-chain design.
  5. sidechain: Another geth instance, this one running our testnet's "sidechain".
  6. ipfs: An IPFS node responsible for hosting all artifacts in our development testnet.
  7. postgres: A datastore for contractor
  8. deposit_*: balancemanager instances that use the relay nodes to move NCT from homechain to sidechain on behalf of their corresponding participant
  9. relay[0-2]: Nodes responsible for managing and selectively releasing escrowed funds across blockchains (e.g. homechain and sidechain). These nodes provide a "relay" abstraction API that participants can use to easily "relay" funds across chains.
  10. ambassador-eicar: A simple Ambassador that places bounties on the EICAR file and on a file that is not EICAR.
  11. microengine-eicar: A simple Microengine that will identify the EICAR file as malicious and all other artifacts as benign.
  12. arbiter-verbatim: A simple Arbiter that delivers scripted ground truth votes, including an accurate EICAR response.

Browse through the logs to get a sense for what each of these components is doing.

Let it run for at least 5 minutes - it can take time to deploy contracts.

When you've seen enough log output, press Ctrl-C to halt the development testnet gracefully.

Test Your Participant

We'll use orchestration to start the entire testnet with one exception: we will not launch a competing version of the participant we're testing.

If we're developing a custom arbiter, for example, we don't want the stock arbiter stepping on our toes.

Prior to testing your participant, rebuild your participant's image, as necessary.

Testing Microengines

Linux-Based Engines

Execute the following in the orchestration directory (replace YOUR_PARTICIPANT_DIRECTORY):

$ docker-compose -f base.yml -f arbiter-verbatim.yml -f ambassador-eicar.yml pull
$ docker-compose -f base.yml -f arbiter-verbatim.yml -f ambassador-eicar.yml -f ../YOUR_PARTICIPANT_DIRECTORY/docker/test-integration.yml up

After the containers have been created, follow your participant's container for log messages (replace YOUR_PARTICIPANT_DIRECTORY and YOUR_PARTICIPANT_SERVICE_NAME):

docker-compose -f base.yml -f arbiter-verbatim.yml -f ambassador-eicar.yml -f ../YOUR_PARTICIPANT_DIRECTORY/docker/test-integration.yml logs --follow YOUR_PARTICIPANT_SERVICE_NAME
Observe Output

Observe your microengine's output to ensure that your microengine is seeing and responding to the incoming bounties.

Windows-Based Engines

Your microengine's "worker", the Docker service responsible for implementing scan logic, is the only Docker service that we will be running on your Windows host.

Your engine's frontend, redis, balancemanager and the rest of the testnet will run on your Linux VM.

Launch the Base Network + an Arbiter

Execute the following in the orchestration directory:

$ docker-compose -f base.yml -f arbiter-verbatim.yml pull
$ docker-compose -f base.yml -f arbiter-verbatim.yml up
Wait for polyswarmd to Become Available

It will take several minutes for polyswarmd to become available. During this time, you will see many messages like Problem with dial... dial tcp connection refused. and chain for config not available in consul yet. These errors are normal while the testnet is initializing, so have patience.

In a new shell, execute the following in the orchestration directory:

$ docker-compose -f base.yml logs --follow polyswarmd

In this new shell, wait for polyswarmd:

Attaching to orchestration_polyswarmd_1_c1d732ac5355
polyswarmd_1_c1d732ac5355 | [2019-05-13 20:52:36 +0000] [1] [INFO] Starting gunicorn 19.9.0
polyswarmd_1_c1d732ac5355 | [2019-05-13 20:52:36 +0000] [1] [INFO] Listening at: http://0.0.0.0:31337 (1)
...
polyswarmd_1_c1d732ac5355 | CRITICAL:polyswarmd.wsgi:polyswarmd is ready!
polyswarmd_1_c1d732ac5355 | CRITICAL:polyswarmd.wsgi:polyswarmd is ready!
polyswarmd_1_c1d732ac5355 | CRITICAL:polyswarmd.wsgi:polyswarmd is ready!
polyswarmd_1_c1d732ac5355 | CRITICAL:polyswarmd.wsgi:polyswarmd is ready!

When ready, polyswarmd will print polyswarmd is ready! once for every polyswarmd thread (4 by default).

Launch BalanceManager + Redis + Microengine Frontend

Share your microengine's root directory with your Linux VM.

In a new shell, execute the following in the root of your microengine's directory (replace YOUR_ENGINE_SLUG with, e.g. eicar):

$ docker-compose -f docker/test-integration.yml up --scale test_microengine-worker_YOUR_ENGINE_SLUG=0
Launch Your Microengine Worker

Launch your engine's Docker container and get an interactive PowerShell:

PS > docker run --isolation=process --network "PolySwarm Network" -it microengine-eicar

In this PowerShell session, launch your microengine, (replace the --backend argument for your engine's package_slug):

[container] PS > microengine --log INFO --keyfile microengine_keyfile --password password --polyswarmd-addr polyswarmd:31337 --insecure-transport --testing 2 --backend <YOUR ENGINES_PACKAGE_SLUG>
Launch an Ambassador to Introduce Bounties

Execute the following in the orchestration directory:

$ docker-compose -f ambassador-eicar.yml pull
$ docker-compose -f ambassador-eicar.yml up

The ambassador's balancemanager may print out many scary messages about insufficient funds while starting up.

This is normal and should stop after balancemanager is able to move the ambassador's funds from the testnet homechain to the testnet sidechain.

Observe Output

Observe your microengine's output to ensure that your microengine is seeing and responding to the incoming bounties.

Testing Ambassadors

Execute the following in the orchestration directory (replace YOUR_PARTICIPANT_DIRECTORY):

$ docker-compose -f base.yml -f arbiter-verbatim.yml -f microengine-eicar.yml pull
$ docker-compose -f base.yml -f arbiter-verbatim.yml -f microengine-eicar.yml -f ../YOUR_PARTICIPANT_DIRECTORY/docker/test-integration.yml up

After the containers have been created, follow your participant's container for log messages (replace YOUR_PARTICIPANT_DIRECTORY and YOUR_PARTICIPANT_SERVICE_NAME):

docker-compose -f base.yml -f arbiter-verbatim.yml -f microengine-eicar.yml -f ../YOUR_PARTICIPANT_DIRECTORY/docker/test-integration.yml logs --follow YOUR_PARTICIPANT_SERVICE_NAME
Observe Output

Observe your ambassadors's output to ensure that your ambassador is successfully submitting bounties.

Next Steps

If you're satisfied with your participant's performance on the testnet, it's time to connect to the real PolySwarm network!

Connecting to the Marketplace →