github.com/kubeshop/testkube@v1.17.23/contrib/executor/tracetest/README.md (about) 1  2 3 # Welcome to TestKube Tracetest Executor 4 5 TestKube Tracetest Executor is a test executor to run [Tracetest](https://tracetest.io/) tests with [TestKube](https://testkube.io). 6 7 # Running Tracetest with Testkube 8 9 [Tracetest](https://tracetest.io/) is a testing tool based on [OpenTelemetry](https://opentelemetry.io/) 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. 10 11 [Testkube](https://testkube.io/) 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. 12 13 By using the [Testkube Tracetest Executor](https://github.com/kubeshop/testkube-executor-tracetest) you can unlock Testkube's capacity in conjunction with Tracetest, and leverage the work you have already done to instrument your services. 14 15 ## Quickstart 16 17 Here we will show how to use Testkube alongside Tracetest to run your tests in a Kubernetes cluster. 18 19 ### Prerequisites 20 21 In your Kubernetes cluster you should have: 22 23 1. `Testkube`: Use HELM or the Testkube CLI to [install](https://kubeshop.github.io/testkube/installing) Testkube Server components in your cluster. 24 2. `Tracetest`: You need a running instance of [Tracetest](https://docs.tracetest.io/getting-started/installation/) or [Tracetest Core](https://docs.tracetest.io/core/getting-started/installation/) which is going to be executing your assertions. To do so you can follow the instructions defined in the Tracetest [documentation](https://docs.tracetest.io/getting-started/overview). 25 3. `OpenTelemetry Instrumented Service`: To generate traces and spans, the service under test must support the basics for [propagation](https://opentelemetry.io/docs/reference/specification/context/api-propagators/) through HTTP requests, and also store traces and spans in a Data Store Backend (Jaeger, Grafana Tempo, OpenSearch, etc) or use the [OpenTelemetry Collector](https://docs.tracetest.io/configuration/overview#using-tracetest-without-a-trace-data-store). 26 27 On your machine you should have: 28 29 1. `Kubectl` [installed](https://kubernetes.io/docs/tasks/tools/) 30 2. `Testkube CLI` [installed](https://kubeshop.github.io/testkube/installing#1-installing-the-testkube-cli) 31 32 With everything set up, we will start configuring Testkube and Tracetest. 33 34 ### 1. Deploy the Tracetest Executor 35 36 Testkube works with the concept of [Executors](https://kubeshop.github.io/testkube/test-types/executor-custom). 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: 37 38 ```bash 39 kubectl testkube create executor --image kubeshop/testkube-executor-tracetest:latest --types "tracetest/test" --name tracetest-executor 40 ``` 41 42 ### 2. Create your test 43 44 Now you need a Tracetest test. Have a look at the [Tracetest documentation](https://docs.tracetest.io/cli/creating-tests) for details on writing tests. Here is a simple test definition example: 45 46 ```yaml 47 type: Test 48 spec: 49 id: R5NITR14g 50 name: Pokeshop - List 51 description: Get a Pokemon 52 trigger: 53 type: http 54 httpRequest: 55 url: http://demo-pokemon-api.demo/pokemon?take=20&skip=0 56 method: GET 57 headers: 58 - key: Content-Type 59 value: application/json 60 specs: 61 - selector: span[tracetest.span.type="http"] 62 assertions: 63 - attr:http.method = "GET" 64 - selector: span[tracetest.span.type="database"] 65 assertions: 66 - attr:db.name = "pokeshop" 67 ``` 68 69 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`: 70 71 ```bash 72 kubectl testkube create test --file my/file/location.yaml --type "tracetest/test" --name pokeshop-tracetest-test --variable TRACETEST_ENDPOINT=http://tracetest 73 ``` 74 75 ### 3. Run your test 76 77 Finally, to see the integration working, you only need to run the test by executing the following command: 78 79 ```bash 80 kubectl testkube run test --watch pokeshop-tracetest-test 81 ``` 82 83 # Architecture 84 85 The following is a high-level sequence diagram of how Testkube and Tracetest interact with the different pieces of the system: 86 87 ```mermaid 88 sequenceDiagram 89 participant testkubeClient as Testkube Client 90 participant testkube as Testkube 91 participant executorCRDs as Executor CRDs 92 participant tracetestExecutorJob as Tracetest Executor Job 93 participant tracetestServer as Tracetest 94 participant instrumentedService as Instrumented Service 95 participant dataStore as Data Store 96 97 testkubeClient->>+testkube: Trigger Testkube test run 98 testkube->>+executorCRDs: Get executor details 99 executorCRDs-->>-testkube: Send details 100 testkube->>+tracetestExecutorJob: Schedules execution 101 tracetestExecutorJob->>+tracetestExecutorJob: Configure Tracetest CLI 102 tracetestExecutorJob->>+tracetestServer: Executes the Tracetest test run 103 tracetestServer->>+instrumentedService: Trigger request 104 instrumentedService-->>-tracetestServer: Get response 105 instrumentedService->>+dataStore: Send telemetry data 106 tracetestServer->>+dataStore: Fetch trace 107 dataStore-->>-tracetestServer: Get trace 108 tracetestServer->>+tracetestServer: Run assertions 109 tracetestServer-->>-tracetestExecutorJob: Return test run results 110 tracetestExecutorJob-->>-testkube: Return test run results 111 testkube-->>-testkubeClient: Send details 112 ``` 113 114 # Issues and enhancements 115 116 Please follow the main [TestKube repository](https://github.com/kubeshop/testkube) for reporting any [issues](https://github.com/kubeshop/testkube/issues) or [discussions](https://github.com/kubeshop/testkube/discussions) 117 118 # Testkube 119 120 For more info go to [main testkube repo](https://github.com/kubeshop/testkube) 121 122  [](https://github.com/kubeshop/testkube/tags?label=Downloads)  123 124    125 126  127 128 #### [Documentation](https://kubeshop.github.io/testkube) | [Slack](https://testkubeworkspace.slack.com/join/shared_invite/zt-2arhz5vmu-U2r3WZ69iPya5Fw0hMhRDg#/shared-invite/email) 129 130 # Tracetest 131 132 For more info go to [main tracetest repo](https://github.com/kubeshop/tracetest) 133 134  135 136 #### [Documentation](https://docs.tracetest.io/) | [Slack](https://testkubeworkspace.slack.com/join/shared_invite/zt-2arhz5vmu-U2r3WZ69iPya5Fw0hMhRDg#/shared-invite/email)