{"id":13630355,"url":"https://github.com/testground/testground","last_synced_at":"2026-01-12T00:37:04.172Z","repository":{"id":37427560,"uuid":"197244214","full_name":"testground/testground","owner":"testground","description":"🧪 A platform for testing, benchmarking, and simulating distributed and p2p systems at scale.","archived":false,"fork":false,"pushed_at":"2024-05-24T14:13:41.000Z","size":33581,"stargazers_count":427,"open_issues_count":234,"forks_count":75,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-08-15T05:21:06.841Z","etag":null,"topics":["continuous-integration","distributed-systems","p2p","testing"],"latest_commit_sha":null,"homepage":"https://testground.github.io/docs","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/testground.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-16T18:05:41.000Z","updated_at":"2025-08-07T03:02:27.000Z","dependencies_parsed_at":"2024-06-18T13:40:49.104Z","dependency_job_id":"77401294-1cd2-4a56-a027-3fa02c27b19a","html_url":"https://github.com/testground/testground","commit_stats":{"total_commits":892,"total_committers":43,"mean_commits":20.74418604651163,"dds":0.7690582959641256,"last_synced_commit":"58ab9a2155715669c3ef9ac3f15a70530b49af0d"},"previous_names":["ipfs/testground"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/testground/testground","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testground%2Ftestground","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testground%2Ftestground/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testground%2Ftestground/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testground%2Ftestground/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/testground","download_url":"https://codeload.github.com/testground/testground/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testground%2Ftestground/sbom","scorecard":{"id":493838,"data":{"date":"2025-08-11","repo":{"name":"github.com/testground/testground","commit":"caa561454926f66eaca26f8f18f44227c339d1af"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.1,"checks":[{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":9,"reason":"Found 24/26 approved changesets -- score normalized to 9","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/integration-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/labels-sync.yml:1","Warn: no topLevel permission defined: .github/workflows/pr-update-on-author-input.yml:1","Warn: no topLevel permission defined: .github/workflows/testground-publish-edge.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE-APACHE:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/testground-publish-edge.yml:33"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Pinned-Dependencies","score":1,"reason":"dependency not pinned by hash detected -- score normalized to 1","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/integration-tests.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/integration-tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/integration-tests.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/integration-tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/labels-sync.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/labels-sync.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/testground-publish-edge.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/testground-publish-edge.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/testground-publish-edge.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/testground-publish-edge.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/testground-publish-edge.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/testground-publish-edge.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/testground-publish-edge.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/testground-publish-edge.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/testground-publish-edge.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/testground-publish-edge.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/testground-publish-edge.yml:43: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/testground-publish-edge.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/testground-publish-edge.yml:48: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/testground-publish-edge.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/testground-publish-edge.yml:55: update your workflow using https://app.stepsecurity.io/secureworkflow/testground/testground/testground-publish-edge.yml/master?enable=pin","Warn: containerImage not pinned by hash: Dockerfile.sidecar:9","Warn: containerImage not pinned by hash: Dockerfile.sidecar:28: pin your Docker image by updating debian:buster to debian:buster@sha256:58ce6f1271ae1c8a2006ff7d3e54e9874d839f573d8009c20154ad0f2fb0a225","Warn: containerImage not pinned by hash: Dockerfile.testground:9","Warn: containerImage not pinned by hash: Dockerfile.testground:28","Warn: containerImage not pinned by hash: plans/_integrations/Dockerfile:1","Warn: containerImage not pinned by hash: plans/_integrations/Dockerfile:13: pin your Docker image by updating busybox:1.31.1-glibc to busybox:1.31.1-glibc@sha256:1f81263701cddf6402afe9f33fca0266d9fff379e59b1748f33d3072da71ee85","Warn: containerImage not pinned by hash: plans/_integrations_mixed_builders/generic/Dockerfile:2","Warn: containerImage not pinned by hash: plans/_integrations_mixed_builders/generic/Dockerfile:11","Warn: containerImage not pinned by hash: plans/example-browser-node/Dockerfile:2: pin your Docker image by updating node:16 to node:16@sha256:f77a1aef2da8d83e45ec990f45df50f1a286c5fe8bbfb8c6e4246c6389705c0b","Warn: containerImage not pinned by hash: plans/example-browser-node/Dockerfile:5: pin your Docker image by updating mcr.microsoft.com/playwright:v1.27.1-focal to mcr.microsoft.com/playwright:v1.27.1-focal@sha256:76a5b662f8664eddebe89383e920af4fc3d4ac0b62f0ff94281dbc337d0a9dd6","Warn: containerImage not pinned by hash: plans/example-rust/Dockerfile:1","Warn: containerImage not pinned by hash: plans/example-rust/Dockerfile:17: pin your Docker image by updating debian:bullseye-slim to debian:bullseye-slim@sha256:849d9d34d5fe0bf88b5fb3d09eb9684909ac4210488b52f4f7bbe683eedcb851","Warn: containerImage not pinned by hash: plans/example/Dockerfile:4","Warn: containerImage not pinned by hash: plans/example/Dockerfile:10","Info:   0 out of   6 GitHub-owned GitHubAction dependencies pinned","Info:   2 out of   7 third-party GitHubAction dependencies pinned","Info:   0 out of  14 containerImage dependencies pinned","Info:   1 out of   1 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"73 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2022-0635","Warn: Project is vulnerable to: GO-2022-0646","Warn: Project is vulnerable to: GO-2022-0649 / GHSA-g7v2-2qxx-wjrw","Warn: Project is vulnerable to: GO-2022-0708 / GHSA-v4h8-794j-g8mm","Warn: Project is vulnerable to: GHSA-qrqr-3x5j-2xw9","Warn: Project is vulnerable to: GHSA-j249-ghv5-7mxv","Warn: Project is vulnerable to: GHSA-6hwg-w5jg-9c6x","Warn: Project is vulnerable to: GO-2024-2521","Warn: Project is vulnerable to: GO-2024-2500 / GHSA-3fwx-pjgw-3558","Warn: Project is vulnerable to: GO-2024-2913 / GHSA-v994-f8vw-g7j4","Warn: Project is vulnerable to: GO-2024-2914 / GHSA-xmmx-7jpf-fx42","Warn: Project is vulnerable to: GO-2022-0390 / GHSA-2mm7-x5h6-5pvq","Warn: Project is vulnerable to: GO-2022-0985 / GHSA-rc4r-wh2q-q6c4","Warn: Project is vulnerable to: GO-2022-1107 / GHSA-vp35-85q5-9f25","Warn: Project is vulnerable to: GHSA-jq35-85cj-fj4p","Warn: Project is vulnerable to: GHSA-mq39-4gv4-mvpx","Warn: Project is vulnerable to: GO-2024-2512 / GHSA-xw73-rw38-6vjc","Warn: Project is vulnerable to: GO-2025-3829 / GHSA-4vq8-7jfc-9cvp","Warn: Project is vulnerable to: GO-2024-2456 / GHSA-449p-3h89-pw88","Warn: Project is vulnerable to: GO-2024-2466 / GHSA-mw99-9chc-xw7r","Warn: Project is vulnerable to: GO-2025-3367 / GHSA-r9px-m959-cxf4","Warn: Project is vulnerable to: GO-2025-3368 / GHSA-v725-9546-7q7m","Warn: Project is vulnerable to: GHSA-h74j-692g-48mq","Warn: Project is vulnerable to: GO-2025-3605 / GHSA-7vpp-9cxj-q8gv","Warn: Project is vulnerable to: GO-2024-2698 / GHSA-rhh4-rh7c-7r5v","Warn: Project is vulnerable to: GHSA-3f2q-6294-fmq5","Warn: Project is vulnerable to: GO-2022-0236 / GHSA-h86h-8ppg-mxmh","Warn: Project is vulnerable to: GO-2021-0238 / GHSA-83g2-8m93-v3w7","Warn: Project is vulnerable to: GO-2022-0288","Warn: Project is vulnerable to: GO-2022-0969 / GHSA-69cg-p879-7622","Warn: Project is vulnerable to: GO-2022-1144 / GHSA-xrjj-mj9h-534m","Warn: Project is vulnerable to: GO-2023-1571 / GHSA-vvpx-j8f3-3w6h","Warn: Project is vulnerable to: GO-2023-1988 / GHSA-2wrh-6pvc-2jm9","Warn: Project is vulnerable to: GO-2023-2102 / GHSA-4374-p667-p6c8","Warn: Project is vulnerable to: GHSA-qppj-fm5r-hxr3","Warn: Project is vulnerable to: GO-2024-2687 / GHSA-4v7x-pqxf-cx7m","Warn: Project is vulnerable to: GO-2024-3333","Warn: Project is vulnerable to: GO-2025-3503 / GHSA-qxp5-gwg8-xv66","Warn: Project is vulnerable to: GO-2025-3595 / GHSA-vvgc-356p-c3xw","Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92","Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc","Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx","Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j","Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w","Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw","Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg","Warn: Project is vulnerable to: GHSA-76p7-773f-r4q5","Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p","Warn: Project is vulnerable to: GHSA-52f5-9888-hmc6","Warn: Project is vulnerable to: GHSA-hc6q-2mpp-qw7j","Warn: Project is vulnerable to: GHSA-4vvj-4cpr-p986","Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7","Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q","Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c","Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9","Warn: Project is vulnerable to: RUSTSEC-2022-0078 / GHSA-f85w-wvc7-crwc","Warn: Project is vulnerable to: RUSTSEC-2020-0159","Warn: Project is vulnerable to: RUSTSEC-2023-0034 / GHSA-f8vr-r385-rh5r","Warn: Project is vulnerable to: RUSTSEC-2024-0003 / GHSA-8r5v-vm4m-4g25","Warn: Project is vulnerable to: RUSTSEC-2024-0332 / GHSA-q6cp-qfwq-4gcv","Warn: Project is vulnerable to: RUSTSEC-2024-0421 / GHSA-h97m-ww89-6jmq","Warn: Project is vulnerable to: RUSTSEC-2024-0384","Warn: Project is vulnerable to: RUSTSEC-2024-0019 / GHSA-r8w9-5wcg-vfj7","Warn: Project is vulnerable to: RUSTSEC-2024-0370","Warn: Project is vulnerable to: GHSA-rr8g-9fpq-6wmg","Warn: Project is vulnerable to: RUSTSEC-2025-0023","Warn: Project is vulnerable to: GO-2022-0493 / GHSA-p782-xgp4-8hr8","Warn: Project is vulnerable to: GO-2022-0603 / GHSA-hp87-p4gw-j4gq"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-19T19:56:03.434Z","repository_id":37427560,"created_at":"2025-08-19T19:56:03.434Z","updated_at":"2025-08-19T19:56:03.434Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28329806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"ssl_error","status_checked_at":"2026-01-12T00:36:15.229Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["continuous-integration","distributed-systems","p2p","testing"],"created_at":"2024-08-01T22:01:39.827Z","updated_at":"2026-01-12T00:37:04.156Z","avatar_url":"https://github.com/testground.png","language":"Go","funding_links":[],"categories":["Go","testing"],"sub_categories":[],"readme":"# Testground\n\n![Testground logo](https://raw.githubusercontent.com/testground/pm/master/logo/TG_Banner_GitHub.jpg)\n\n[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://protocol.ai)\n![](https://img.shields.io/badge/go-%3E%3D1.16.0-blue.svg)\n[![Go Report Card](https://goreportcard.com/badge/testground/testground)](https://goreportcard.com/report/testground/testground)\n[![CircleCI](https://circleci.com/gh/testground/testground.svg?style=svg)](https://circleci.com/gh/testground/testground)\n\nTestground is a platform for testing, benchmarking, and simulating distributed and p2p\nsystems at scale. It's designed to be multi-lingual and runtime-agnostic, scaling gracefully\nfrom 2 to 10k instances, only when needed.\n\n![Testground demo](https://github.com/testground/pm/blob/master/img/testground-demo.gif?raw=true)\n\n## Table of Contents\n\n\u003c!-- INSTRUCTIONS: regenerate with [doctoc](https://github.com/thlorenz/doctoc) --\u003e\n\u003c!-- Command: doctoc README.md --maxlevel=2 --\u003e\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Getting started](#getting-started)\n- [Documentation](#documentation)\n- [How does it work?](#how-does-it-work)\n- [Features](#features)\n- [Where to find test plans?](#where-to-find-test-plans)\n- [Contributing](#contributing)\n- [Team](#team)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Getting started\n\n_NOTE: currently, we don't distribute binaries, so you will have to build from source._\n\n***Prerequisites: Go 1.16+, Docker daemon running.***\n\n```shell script\n$ git clone https://github.com/testground/testground.git\n\n$ cd testground\n\n$ make install       # builds testground and the Docker image, used by the local:docker runner.\n\n$ testground daemon  # will start the daemon listening on localhost:8042 by default.\n\n# =\u003e open a different console (client-side), in the same directory (testground/testground repo checkout)\n\n# import the network test plan from this repo into $TESTGROUND_HOME/plans\n# read more about this path at https://docs.testground.ai/getting-started#running-testground\n$ testground plan import --from ./plans/network\n\n# run two instances of the `ping-pong` test case from the `network` plan,\n# building with docker:go, running with local:docker\n$ testground run single --plan=network --testcase=ping-pong \\\n                        --builder=docker:go --runner=local:docker \\\n                        --instances=2\n``` \n\n**See [Getting started](https://docs.testground.ai/getting-started) and the rest of the docs on our [docs website](https://docs.testground.ai/) for more info! 🚀**\n\n## Documentation\n\nThis README is just the tip of the iceberg! **Check out our full documentation site at [docs.testground.ai](https://docs.testground.ai).**\n\nThere you will find a conceptual system walkthrough, tips on writing test plans, instructions on running test plans, configuring runners and builders, deploying Kubernetes clusters, and a lot more.\n\nPlease report any problems or inaccuracies by [opening a docs issue on this repo](https://github.com/testground/testground/issues/new?assignees=\u0026labels=docs\u0026template=DOCS.md\u0026title=docs%20site:%20%3Cdescribe%20the%20problem%3E).\n\n## How does it work?\n\n1. **You develop distributed test plans as if you were writing unit tests against local APIs.**\n    - No puppeteering necessary.\n    - No need to package and ship the system or component under test as a separate daemon.\n    - No need to expose every internal setting over an external API, just for the sake of testing.\n    \n2. **Your test plan calls out to the coordination API to:**\n    - communicate out-of-band information (such as endpoint addresses, peer ids, etc.)\n    - leverage synchronization and ordering primitives such as signals and barriers to model a\n       distributed state machine.\n    - programmatically apply network traffic shaping policies, which you can alter during the\n       execution of a test to simulate various network conditions.\n       \n3. **There is no special \"conductor\" node telling instances what to do when.** The choreography and\n   sequencing emerges from within the test plan itself.\n   \n4. **You decide what versions of the upstream software you want to exercise your test against.**\n     - Benchmark, simulate, experiment, run attacks, etc. against versions v1.1 and v1.2 of the\n       components under test in order to compare results, or test compatibility.\n     - Assemble hybrid test runs mixing various versions of the dependency graph.\n     \n5. **Inside your test plan:**\n     - You record observations, metrics, success/failure statuses.\n     - You emit structured or unstructured assets you want collected, such as event logs,\n       dumps, snapshots, binary files, etc.\n        \n6. **Via a TOML-based _composition_ file, you instruct Testground to:**\n     - Assemble a test run comprising groups of 2, 200, or 10000 instances, each with different\n       test parameters, or built against different depencency sets.\n     - Schedule them for run locally (executable or Docker), or in a cluster (Kubernetes).\n     \n7. **You collect the outputs of the test plan with a single command,** and use data processing scripts and\n   platforms (such as the upcoming Jupyter notebooks integration) to draw conclusions.\n\n## Features\n\nFor the short and long term roadmap see [ROADMAP.md](./ROADMAP.md).\n\n### Supports (or aims to support) a variety of testing workflows 💡\n\n\u003e (🌕 = fully supported // 🌑 = planned)\n\n  * Experimental/iterative development 🌖 (The team at Protocol Labs has used Testground extensively to evaluate\n    protocol changes in large networks, simulate attacks, measure algorithmic improvements across network boundaries,\n    etc.) \n  * Debugging 🌗\n  * Comparative testing 🌖\n  * Backwards/forward-compatibility testing 🌖 \n  * Interoperability testing 🌑\n  * Continuous integration 🌑\n  * Stakeholder/acceptance testing 🌑\n\n### Simple, normalized, formal runtime environment for tests 📄\n\nA test plan is a blackbox with a formal contract. Testground promises to inject a set of env variables, and the test\nplan promises to emit events on stdout, and assets on the output directory.\n  * As such, a test plan can be any kind of program, written in Go, JavaScript, C, or shell.\n  * At present, we offer builders for Go, with TypeScript (node and browser) being in the works.  \n\n### Modular builders and runners 🛠\n\nFor running test plans written in different languages, targeted for different runtimes, and levels of scale:\n  * `exec:go` and `docker:go` builders: compile test plans written in Go into executables or containers.\n  * `local:exec`, `local:docker`, `cluster:k8s` runners: run executables or containers locally\n    (suitable for 2-300 instances), or in a Kubernetes cloud environment (300-10k instances).\n\n\u003e Got some spare cycles and would like to add support for writing test plans Rust, Python or X? It's easy! Open an\n\u003e issue, and the community will guide you!\n\n### Distributed coordination API 👯‍♀️\n\nRedis-backed lightweight API offering synchronisation primitives to coordinate and choreograph distributed test\nworkloads across a fleet of nodes.\n\n### Network traffic shaping ☎️\n\nTest instances are able to set connectedness, latency, jitter, bandwidth, duplication, packet corruption, etc. to\nsimulate a variety of network conditions.\n\n### Quickstart k8s cluster setup on AWS ☁️\n\nCreate a k8s cluster ready to run Testground jobs on AWS by following the instructions at\n[`testground/infra`](https://github.com/testground/infra).\n\n### Upstream dependency selection 🧩\n\nCompiling test plans against specific versions of upstream dependencies (e.g. moduleX v0.3, or commit 1a2b3c).\n\n### Dealing with upstream API changes 🌱\n\nSo that a single test plan can work with a range of versions of the components under test, as these evolve over time.\n\n### Results and diagnostics, raw and aggregated data points 📈\n\n**Diagnostics:** Automatic diagnostics via pprof (for Go test plans), with metrics emitted to InfluxDB in real-time. Metrics can be raw data points or aggregated measurements, such as histograms, counters, gauges, moving averages, etc.\n\n**Results:** When the test plan concludes, all results are pushed in batch to InfluxDB for later exploration, analysis, and visualization.\n\n### Declarative jobs, we call them _compositions_ 🎼\n\nCreate tailored test runs by composing scenarios declaratively, with different groups, cohorts, upstream deps, test\nparams, etc. \n\n### Emit and collect test outputs 💾\n\nEmit and collect/export/download test outputs (logs, assets, event trails, run events, etc.) from all participants\nin a run. \n\n## Where to find test plans?\n\nThere are some basic, project-agnostic Testground test plans in the [`plans`](./plans) directory.\nWe use these plans to validate the functionality of Testground itself.\n\nTo link them under `$TESTGROUND_HOME/plans`, if you're using default paths, these commands should do the trick\n(assuming you have already run the Testground daemon once, and therefore the `$TESTGROUND_HOME` layout has been created\nfor you):\n\n```shell script\n$ # from the root of this repo, run the following; it will symlink all test plans under $TESTGROUND_HOME/plans\n$ ln -s $PWD/plans/* $HOME/testground/plans\n$ testground run single --plan network --testcase ping-pong --builder=docker:go --runner=local:docker --instances=2\n```\n\nFor project-specific test plans, check out these repos:\n\n* https://github.com/libp2p/test-plans\n* https://github.com/ipfs/test-plans\n\nTo use them, import them into `$TESTGROUND_HOME/plans` using the following testground commands:\n\n```shell script\n$ testground plan import --git --from https://github.com/libp2p/test-plans.git --name libp2p\n$ testground plan import --git --from https://github.com/ipfs/test-plans.git --name ipfs\n$ # to run the find-peers test case from the libp2p/dht test plan (this is not a complete command!)\n$ testground run single --plan libp2p/dht --testcase find-peers --builder docker:go --runner local:docker \u003coptions\u003e\n``` \n\n## Contributing\n\nPlease read our [CONTRIBUTING Guidelines](./CONTRIBUTING.md) before making a contribution.\n\n## Team\n\n### Core team 💪\n\n* [@raulk](https://github.com/raulk) 🎈 _(founder, project lead, technical product owner, architect)_\n* [@nonsense](https://github.com/nonsense) ⛷ _(tech lead + core engineer)_\n* [@coryschwartz](https://github.com/coryschwartz) 🦉 _(core engineer)_\n* [@hacdias](https://github.com/hacdias) 😂 _(core engineer)_\n\n### Collaborators ❤\n\n[@daviddias](https://github.com/daviddias), [@stebalien](https://github.com/stebalien), [@jimpick](https://github.com/jimpick), [@aschmahmann](https://github.com/aschmahmann), [@dirkmc](https://github.com/dirkmc), [@yusefnapora](https://github.com/yusefnapora).\n\n### Meeting notes\n\nYou can find notes from the Testground team meetings at [github.com/testground/pm](https://github.com/testground/pm/tree/master/_meeting-notes)\n\n## License\n\nDual-licensed: [MIT](./LICENSE-MIT), [Apache Software License v2](./LICENSE-APACHE), by way of the\n[Permissive License Stack](https://protocol.ai/blog/announcing-the-permissive-license-stack/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestground%2Ftestground","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftestground%2Ftestground","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestground%2Ftestground/lists"}