tracetest/

README

Welcome to TestKube Tracetest Executor

TestKube Tracetest Executor is a test executor to run Tracetest tests with TestKube.

Running Tracetest with Testkube

Tracetest is a testing tool based on OpenTelemetry that permits you to test your distributed application. It allows you to use the trace data generated by your OpenTelemetry tools to check and assert if your application has the desired behavior defined by your test definitions.

Testkube is a Kubernetes-native testing framework for Testers and Developers that allows you to automate the executions of your existing testing tools inside your Kubernetes cluster, removing all the complexity from your CI/CD/GitOps pipelines.

By using the Testkube Tracetest Executor you can unlock Testkube's capacity in conjunction with Tracetest, and leverage the work you have already done to instrument your services.

Quickstart

Here we will show how to use Testkube alongside Tracetest to run your tests in a Kubernetes cluster.

Prerequisites

In your Kubernetes cluster you should have:

1. Testkube: Use HELM or the Testkube CLI to install Testkube Server components in your cluster.
2. Tracetest: You need a running instance of Tracetest or Tracetest Core which is going to be executing your assertions. To do so you can follow the instructions defined in the Tracetest documentation.
3. OpenTelemetry Instrumented Service: To generate traces and spans, the service under test must support the basics for propagation through HTTP requests, and also store traces and spans in a Data Store Backend (Jaeger, Grafana Tempo, OpenSearch, etc) or use the OpenTelemetry Collector.

On your machine you should have:

1. Kubectl installed
2. Testkube CLI installed

With everything set up, we will start configuring Testkube and Tracetest.

1. Deploy the Tracetest Executor

Testkube works with the concept of Executors. An Executor is a wrapper around a testing framework (Tracetest in this case) in the form of a Docker container and runs as a Kubernetes job. To start you need to register and deploy the Tracetest executor in your cluster using the Testkube CLI:

kubectl testkube create executor --image kubeshop/testkube-executor-tracetest:latest --types "tracetest/test" --name tracetest-executor

2. Create your test

Now you need a Tracetest test. Have a look at the Tracetest documentation for details on writing tests. Here is a simple test definition example:

type: Test
spec:
  id: R5NITR14g
  name: Pokeshop - List
  description: Get a Pokemon
  trigger:
    type: http
    httpRequest:
      url: http://demo-pokemon-api.demo/pokemon?take=20&skip=0
      method: GET
      headers:
        - key: Content-Type
          value: application/json
  specs:
    - selector: span[tracetest.span.type="http"]
      assertions:
        - attr:http.method = "GET"
    - selector: span[tracetest.span.type="database"]
      assertions:
        - attr:db.name = "pokeshop"

Execute the following command to create the test executor object in Testkube. Do not forget to provide the path to your Tracetest definition file using the --file argument, and also the Tracetest Server endpoint using the TRACETEST_ENDPOINT --variable:

kubectl testkube create test --file my/file/location.yaml --type "tracetest/test" --name pokeshop-tracetest-test --variable TRACETEST_ENDPOINT=http://tracetest

3. Run your test

Finally, to see the integration working, you only need to run the test by executing the following command:

kubectl testkube run test --watch pokeshop-tracetest-test

Architecture

The following is a high-level sequence diagram of how Testkube and Tracetest interact with the different pieces of the system:

sequenceDiagram
    participant testkubeClient as Testkube Client
    participant testkube as Testkube
    participant executorCRDs as Executor CRDs
    participant tracetestExecutorJob as Tracetest Executor Job
    participant tracetestServer as Tracetest
    participant instrumentedService as Instrumented Service
    participant dataStore as Data Store

    testkubeClient->>+testkube:                   Trigger Testkube test run
    testkube->>+executorCRDs:                     Get executor details
    executorCRDs-->>-testkube:                    Send details
    testkube->>+tracetestExecutorJob:             Schedules execution
    tracetestExecutorJob->>+tracetestExecutorJob: Configure Tracetest CLI
    tracetestExecutorJob->>+tracetestServer:      Executes the Tracetest test run
    tracetestServer->>+instrumentedService:       Trigger request
    instrumentedService-->>-tracetestServer:      Get response
    instrumentedService->>+dataStore:             Send telemetry data
    tracetestServer->>+dataStore:                 Fetch trace
    dataStore-->>-tracetestServer:                Get trace
    tracetestServer->>+tracetestServer:           Run assertions
    tracetestServer-->>-tracetestExecutorJob:     Return test run results
    tracetestExecutorJob-->>-testkube:            Return test run results
    testkube-->>-testkubeClient:                  Send details

Issues and enhancements

Please follow the main TestKube repository for reporting any issues or discussions

Testkube

For more info go to main testkube repo

Documentation | Discord

Tracetest

For more info go to main tracetest repo

Documentation | Discord