# Getting started *How to install Testground, and run your first test plan* ## Installing Testground ### Prerequisites * [Docker](https://www.docker.com/products/docker-desktop) * [Go 1.16](https://golang.org/), or higher ### Installation Currently, we don't distribute binaries, so you will have to build from source. ```bash $ git clone https://github.com/testground/testground.git $ cd testground # compile Testground and all related dependencies $ make install ``` ## Running Testground In order to use Testground, you need to have a running Testground daemon. ```bash # start the Testground daemon, listening by default on localhost:8042 # it processes commands received from the Testground client $ testground daemon ``` **`$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: ``` $TESTGROUND_HOME | |__ plans >>> [c] contains test plans, can be git checkouts, symlinks to local dirs, or the source itself | |__ 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. | | |__ plan-1 >>> source of a test plan identified by suite-a/plan-1 (relative to $TESTGROUND_HOME/plans) | | |__ plan-2 | |__ plan-3 >>> source of a test plan identified by plan-3 (relative to $TESTGROUND_HOME/plans) | |__ sdks >>> [c] hosts the test development SDKs that the client knows about, so they can be used with the --link-sdk option. | |__ sdk-go | |__ data >>> [d] data directory |__ outputs |__ work [c] = used client-side // [d] = used mostly daemon-side. ``` ## 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](https://protocol-labs.gitbook.io/testground/table-of-contents/concepts-and-architecture/sync-service) as well as the [traffic shaping](https://protocol-labs.gitbook.io/testground/table-of-contents/traffic-shaping) and IP allocation functionality. Configure `$TESTGROUND_HOME` and copy the example `network` test plan into the `$TESTGROUND_HOME/plans` directory. ```bash # assuming you already started your Testground daemon (as instructed above) # there should be a `testground` directory in your home folder, i.e. `~/testground` # # from your testground/testground Git checkout, run: $ testground plan import --from ./plans/network ... created symlink /Users/raul/testground/plans/network -> ./plans/network imported plans: network ping-pong ``` Run the `network`testplan 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. ```bash $ testground run single \ --plan=network \ --testcase=ping-pong \ --builder=docker:go \ --runner=local:docker \ --instances=2 ``` ?> 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: ``` [...] INFO run finished successfully {"req_id": "d570c53a", "plan": "network", "case": "ping-pong", "runner": "local:docker", "instances": 2} >>> Result: INFO finished run with ID: 5222e5df793b ``` 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): ```bash $ testground collect --runner=local:docker 5222e5df793b [...] >>> Result: INFO created file: 5222e5df793b.tgz ``` Open the bundle and you will find the outputs from the test in there: ![](https://553969225-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M3Ca3OQSAlIMUyorSwi%2F-M6agGdv6hAZFxlSOdt8%2F-M6anMOg6zHtQ7kXZKBS%2Fimage.png?alt=media\&token=214456e1-8e8c-41cf-a2d8-6727bd7f69b9) ## Configuration (.env.toml) `.env.toml`is 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** ```toml [daemon] listen = ":8080" [client] endpoint = "http://localhost:8080" ``` The endpoint refers to the `testground-daemon` service, so depending on your setup, this could be, for example, a Load Balancer fronting the kubernetes cluster and forwarding proper requests to the `tg-daemon` service, or a simple port forward to your local workstation: ``` [client] endpoint = "http://localhost:28015" # in case we use port forwarding, like this one here: kubectl port-forward service/testground-daemon 28015:8042 ``` ### Customize asynchrony You can customize the number of asynchronous workers, as well as the maximum queue capacity, i.e., the maximum number of pending tasks at a moment in time. In addition, you can adjust the workers' task time execution limit. This is a handy option, if you have long-running tests **.env.toml** ``` [daemon.scheduler] workers = 2 queue_size = 100 task_timeout_min = 40 ``` ### AWS integration When using a remote runner such as `cluster:k8s`, you should configure the default region: **.env.toml** ``` ["aws"] region = "aws region, such as eu-central-1" ``` 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** ``` ["dockerhub"] repo = "repo to be used for testground" username = "username" access_token = "docker hub access token" ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://protocol-labs.gitbook.io/testground/table-of-contents/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.