How it works

TestLens is a platform that captures data about all your tests while they are running. This page explains what it does, how it works, which features it has. If you want to onboard your own project quickly, head over to Prerequisites. If you’re interested in TestLens’ features, go to the Features section.

TestLens consists of three parts:

• A GitHub App that you need to install into your GitHub account.
• A GitHub Action that you need to add to your GitHub Actions Workflows.
• An instrumentation client that is injected into each JVM that is executing tests by the setup-testlens action.

Here’s an overview of how the system works:

flowchart TD
    pr["Pull Request"]
    workflow["GitHub Workflow"]
    githubApp@{ shape: cloud, label: "GitHub App"}
    database[("Database")]
    setupAction["setup-testlens"]
    instrumentation["instrumentation client"]
    testVm["Test VM"]

    pr-->|triggers|workflow
    workflow-->|runs|setupAction
    setupAction-->|injects|instrumentation
    instrumentation-->|collects data|testVm
    testVm-->|executes tests|testVm
    instrumentation-->|sends data|githubApp
    githubApp-->|stores data|database
    githubApp-->|posts comment|pr

When a GitHub Actions workflow runs in your repository and the setup-testlens action is present, the action injects TestLens’ instrumentation client into each JVM running tests. Currently, Gradle and Apache Maven™ are supported. Furthermore, tests must be executed via a test engine that runs on top of JUnit Platform. This includes — but is not limited to — JUnit Jupiter, Spock Framework, and KoTest. The instrumentation client opens a connection to the TestLens GitHub App and streams data about the test environment, test results, and test failures while your tests are running. GitHub notifies TestLens once any workflow completes, and TestLens responds to this event by posting an informative comment, that summarizes the results of any test execution that happened while the workflow was running. Additionally, TestLens detects flaky tests across all GitHub Actions workflow executions and summarizes them for you in the Test Dashboard issue.