Getting started
How to install Testground, and run your first test plan
Installing Testground
Prerequisites
Installation
Currently, we don't distribute binaries, so you will have to build from source.
1
$ git clone https://github.com/testground/testground.git
2
​
3
$ cd testground
4
​
5
# compile Testground and all related dependencies
6
$ make install
Copied!
Running Testground
In order to use Testground, you need to have a running Testground daemon.
1
# start the Testground daemon, listening by default on localhost:8042
2
# it processes commands received from the Testground client
3
$ testground daemon
Copied!
$TESTGROUND_HOME is an important directory. If not explicitly set, Testground uses $HOME/testground as a default. The layout of $TESTGROUND_HOME is as follows:1
$TESTGROUND_HOME
2
|
3
|__ plans >>> [c] contains test plans, can be git checkouts, symlinks to local dirs, or the source itself
4
| |__ suite-a >>> test plans can be grouped in suites (which in turn can be nested); this enables you to host many test plans in a single repo / directory.
5
| | |__ plan-1 >>> source of a test plan identified by suite-a/plan-1 (relative to $TESTGROUND_HOME/plans)
6
| | |__ plan-2
7
| |__ plan-3 >>> source of a test plan identified by plan-3 (relative to $TESTGROUND_HOME/plans)
8
|
9
|__ sdks >>> [c] hosts the test development SDKs that the client knows about, so they can be used with the --link-sdk option.
10
| |__ sdk-go
11
|
12
|__ data >>> [d] data directory
13
|__ outputs
14
|__ work
15
​
16
[c] = used client-side // [d] = used mostly daemon-side.
Copied!
Running an example test plan
The first test plan that we will run is the
network test plan and the ping-pong test case.The
ping-pong test case starts 2 test plan instances: one that listens on a TCP socket and another that dials it. The test case exercises the sync service as well as the traffic shaping and IP allocation functionality.Configure
$TESTGROUND_HOME and copy the example network test plan into the $TESTGROUND_HOME/plans directory.1
# assuming you already started your Testground daemon (as instructed above)
2
# there should be a `testground` directory in your home folder, i.e. `~/testground`
3
#
4
# from your testground/testground Git checkout, run:
5
$ testground plan import --from ./plans/network
6
...
7
created symlink /Users/raul/testground/plans/network -> ./plans/network
8
imported plans:
9
network ping-pong
Copied!
Run the
networktestplan and the ping-pong test case with the docker:go builder and the local:docker runner.Make sure you have
testground daemon running in another terminal window.1
$ testground run single \
2
--plan=network \
3
--testcase=ping-pong \
4
--builder=docker:go \
5
--runner=local:docker \
6
--instances=2
Copied!
During the first run the Testground daemon sets up the builder and runner environments. Subsequent runs will be faster.
You should see a flurry of activity, including measurements, messages, and runtime events. When the execution concludes, you will see something like:
1
[...]
2
INFO run finished successfully {"req_id": "d570c53a", "plan": "network", "case": "ping-pong", "runner": "local:docker", "instances": 2}
3
​
4
>>> Result:
5
​
6
INFO finished run with ID: 5222e5df793b
Copied!
In the local runners, all test plan run outputs and logs are stored at
$TESTGROUND_HOME/data. Collect them into a bundle with the following command (replacing 5222e5df793b with the corresponding run ID):1
$ testground collect --runner=local:docker 5222e5df793b
2
[...]
3
​
4
>>> Result:
5
​
6
INFO created file: 5222e5df793b.tgz
Copied!
Open the bundle and you will find the outputs from the test in there:
Configuration (.env.toml)
.env.tomlis a configuration file read by the Testground daemon and the Testground client on startup.Testground tries to load this file from
$TESTGROUND_HOME/.env.toml, where $TESTGROUND_HOME defaults to $HOME/testground by default.Changing default daemon bind addresses
You can change the default bind addresses by configuring
daemon.listen and client.endpoint:.env.toml
1
[daemon]
2
listen = ":8080"
3
​
4
[client]
5
endpoint = "localhost:8080"
Copied!
AWS integration
When using a remote runner such as
cluster:k8s, you should configure the default region:.env.toml
1
["aws"]
2
region = "aws region, such as eu-central-1"
Copied!
The AWS configuration is also used if you push Docker images to AWS ECR from the
docker:go builder using the --build-cfg push_registry=true and --build-cfg registry_type=aws flags.DockerHub integration
If you want to push Docker images from the
docker:go builder to a DockerHub registry, you can configure it..env.toml
1
["dockerhub"]
2
repo = "repo to be used for testground"
3
username = "username"
4
access_token = "docker hub access token"
Copied!
Last modified 1yr ago