PolySwarmPolySwarmPolySwarmPolySwarm
Go to PolySwarm
Home

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.

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 homechain node and relays)
  • sidechain-geth.yml: defines the sidechain node using geth
  • sidechain-parity.yml: defines the sidechain node using parity
  • 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 sidechain-geth.yml -f ambassador-eicar.yml -f microengine-eicar.yml -f arbiter-verbatim.yml pull
$ docker-compose -f base.yml -f sidechain-geth.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

In the following instructions, YOUR_PARTICIPANT_SERVICE_NAME can be found in your participant's docker/test-integration.yml file. Choose the service for which you'd like to view log output:

  • frontends handle interaction with the PolySwarm network
  • workers do the actual work; they're the ones running the Scanner class

You may want to view log output from one or both of these services.

Linux-Based Engines

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

$ docker-compose -f base.yml -f sidechain-geth.yml -f arbiter-verbatim.yml -f ambassador-eicar.yml pull
$ docker-compose -f base.yml -f sidechain-geth.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 container's log messages in another console, while keeping the containers running (replace YOUR_PARTICIPANT_DIRECTORY and YOUR_PARTICIPANT_SERVICE_NAME):

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

YOUR_PARTICIPANT_SERVICE_NAME can be found in your docker/test-integration.yml, e.g. test_microengine-worker_<name of your engine>.

Observe Output

Observe your microengine's output to ensure that your microengine is seeing and responding to the incoming bounties. And to ensure the output contains any other logging messages you wrote.

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 sidechain-geth.yml -f arbiter-verbatim.yml pull
$ docker-compose -f base.yml -f sidechain-geth.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 -f sidechain-geth.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 + 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:

$ docker-compose -f docker/test-integration.yml up
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 > worker --log INFO --testing 2 --queue <YOUR_PARTICIPANT_SLUG> --backend <YOUR_ENGINES_PACKAGE_SLUG>

For example:

[container] PS > worker --log INFO --testing 2 --queue myfirstparticipant --backend polyswarm_myfirstparticipant
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 sidechain-geth.yml -f arbiter-verbatim.yml -f microengine-eicar.yml pull
$ docker-compose -f base.yml -f sidechain-geth.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 sidechain-geth.yml -f arbiter-verbatim.yml -f microengine-eicar.yml -f ../YOUR_PARTICIPANT_DIRECTORY/docker/test-integration.yml logs --follow YOUR_PARTICIPANT_SERVICE_NAME

YOUR_PARTICIPANT_SERVICE_NAME can be found in your participant's docker/test-integration.yml file. There will only be one service for your Ambassador; copy this service name into the above command line to view its log output.

Observe Output

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

Testing Arbiters

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

$ docker-compose -f base.yml -f sidechain-geth.yml -f ambassador-eicar.yml -f microengine-eicar.yml pull
$ docker-compose -f base.yml -f sidechain-geth.yml -f ambassador-eicar.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 sidechain-geth.yml -f ambassador-eicar.yml -f microengine-eicar.yml -f ../YOUR_PARTICIPANT_DIRECTORY/docker/test-integration.yml logs --follow YOUR_PARTICIPANT_SERVICE_NAME

YOUR_PARTICIPANT_SERVICE_NAME can be found in your participant's docker/test-integration.yml file. Choose the service for which you'd like to view log output:

  • frontends handle interaction with the PolySwarm network
  • workers do the actual work - they're the ones running the Scanner class

You may want to view log output from one or both of these services.

Observe Output

Observe your arbiter's output to ensure that your arbiter is seeing and responding to the incoming 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!