Skip to content

Commit f1014f8

Browse files
xoscarxoscar
authored
chore(docs/examples): Adding GraphQL information (#4001)
* chore(docs/examples): Adding GraphQL information * pr fixes * removing unecessary code
1 parent 92b749b commit f1014f8

22 files changed

+885
-0
lines changed

‎docs/docs/cli/creating-tests-graphql.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
id: creating-tests-graphql
3+
title: Defining GraphQL Tests as Text Files
4+
description: Tracetest enables developers to define tests as text files and run them using a CLI. Integrate the execution of tests in your existing CI pipeline.
5+
keywords:
6+
- tracetest
7+
- trace-based testing
8+
- observability
9+
- distributed tracing
10+
- testing
11+
- graphql
12+
image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
13+
---
14+
15+
When defining a GraphQL trigger, you are required to define a `graphql` object containing the request Tracetest will send to your system. You also define: `body` with `query`, `variables` and `operationName`, `url`, `headers`, and `SSLVerification`, and `schema`.
16+
17+
```yaml
18+
trigger:
19+
type: graphql
20+
graphql:
21+
url: ${env:GRAPHQL_URL}
22+
headers:
23+
- key: Content-Type
24+
value: application/json
25+
body:
26+
# path to the query file or the query itself
27+
query: ./query.graphql
28+
variables: {}
29+
operationName: ""
30+
sslVerification: false
31+
# path to the schema file or the schema itself
32+
schema: ./schema.graphql
33+
```

‎docs/docs/examples-tutorials/recipes.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Recipes are short, self-contained, guides for getting started with building popu
2323
These guides show how to get the best of your instrumentation using the native Tracetest Triggers.
2424

2525
- [True End-To-End Trace-Based Tests with the Tracetest Playwright Engine](/examples-tutorials/recipes/running-tests-with-tracetest-playwright-engine)
26+
- [Trace-Based Tests with the Tracetest GrapqhQL Trigger](/examples-tutorials/recipes/running-tests-with-tracetest-graphql-pokeshop)
2627

2728
## Synthetic Monitoring
2829

‎docs/docs/examples-tutorials/recipes/running-tests-with-tracetest-graphql-pokeshop.mdx‎

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
---
2+
id: running-tests-with-tracetest-graphql-pokeshop
3+
title: Trace-Based Tests with the Tracetest GrapqhQL Trigger
4+
description: Quickstart on how to create Trace-Based Tests with the Tracetest GraphQL Trigger
5+
hide_table_of_contents: false
6+
keywords:
7+
- tracetest
8+
- trace-based testing
9+
- observability
10+
- distributed tracing
11+
- end-to-end testing
12+
- tracetest
13+
- graphql
14+
- trace-based-testing
15+
- trigger
16+
image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
17+
---
18+
19+
:::info Version Compatibility
20+
The features described here are compatible with the [Tracetest CLI v1.5.2](https://github.com/kubeshop/tracetest/releases/tag/v1.5.2) and above.
21+
:::
22+
23+
:::note
24+
[Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-jaeger-graphql-pokeshop)
25+
:::
26+
27+
[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.
28+
[GraphQL](https://graphql.org/) is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
29+
30+
## Why is this important?
31+
32+
The Tracetest GraphQL trigger enables you to unleash the power of the trace-based testing to easily capture a full distributed trace from your OpenTelemetry instrumented GraphQL back-end system.
33+
34+
By creating a Tracetest GraphQL test, you will be able to create trace-based assertions to be applied across the entire flow like any other Tracetest test. Not only that but it allows you to mix and match it with your existing Monitors, Test Suites and CI/CD validations.
35+
36+
Other impactful benefits of using traces as test specs are:
37+
38+
- Faster MTTR for failing performance tests.
39+
- Assert against the Mutiple Queries and Mutations at once from a single test execution.
40+
- Validate functionality of other parts of your system that may be broken, even when the initial request is passing.
41+
42+
## Requirements
43+
44+
**Tracetest Account**:
45+
46+
- Sign up to [`app.tracetest.io`](https://app.tracetest.io) or follow the [get started](/getting-started/installation) docs.
47+
- Have access to the environment's [agent API key](https://app.tracetest.io/retrieve-token).
48+
49+
**Docker**: Have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed on your machine.
50+
51+
## Run This Example
52+
53+
The example below is provided as part of the Tracetest GitHub repo. You can download and run the example by following these steps:
54+
55+
```bash
56+
git clone https://github.com/kubeshop/tracetest
57+
cd tracetest/examples/tracetest-jaeger-graphql-pokeshop
58+
```
59+
60+
Follow these instructions to run the quick start:
61+
62+
1. Copy the `.env.template` file to `.env`.
63+
2. Fill out the [TRACETEST_TOKEN and ENVIRONMENT_ID](https://app.tracetest.io/retrieve-token) details by editing your `.env` file.
64+
3. Run `docker compose run tracetest-run`.
65+
4. Follow the links in the output to view the test results.
66+
67+
## Project Structure
68+
69+
The project structure for running Tracetest GraphQL tests is as follows:
70+
71+
```bash
72+
.env.template
73+
.gitignore
74+
.Dockerfile
75+
collector.config.yaml
76+
docker-compose.yaml
77+
/resources
78+
apply.sh
79+
datastore.yaml
80+
test.yaml
81+
run.sh
82+
scheme.graphql
83+
query.graphql
84+
```
85+
86+
The [Pokeshop Demo App](/live-examples/pokeshop/overview) is a complete example of a distributed application using different back-end and front-end services. We will be launching it and running tests against it as part of this example.
87+
The `docker-compose.yaml` file in the root directory of the quick start runs the Pokeshop Demo app, the OpenTelemetry Collector, Jaeger, and the [Tracetest Agent](/concepts/agent) setup.
88+
89+
The Tracetest resource definitions and scripts are defined under the `/resources` directory. The resources include tests and the tracing backend definition, while the scripts include the `apply.sh` and `run.sh` scripts to apply the resources and run the tests.
90+
91+
## Provisioned Resources
92+
93+
The example provisions the following resources:
94+
95+
### Import Pokemon Test
96+
97+
```yaml title="resources/test.yaml"
98+
type: Test
99+
spec:
100+
id: re9XOxqSR
101+
name: Pokeshop - Import
102+
trigger:
103+
type: graphql
104+
graphql:
105+
url: http://demo-api:8081/graphql
106+
headers:
107+
- key: Content-Type
108+
value: application/json
109+
auth:
110+
apiKey: {}
111+
basic: {}
112+
bearer: {}
113+
body:
114+
query: ./query.graphql
115+
variables: {}
116+
operationName: ""
117+
sslVerification: false
118+
schema: ./schema.graphql
119+
specs:
120+
- name: Import Pokemon Span Exists
121+
selector: span[tracetest.span.type="general" name="import pokemon"]
122+
assertions:
123+
- attr:tracetest.selected_spans.count = 1
124+
- name: Uses Correct PokemonId
125+
selector: span[tracetest.span.type="http" name="GET" http.method="GET"]
126+
assertions:
127+
- attr:http.url = "https://pokeapi.co/api/v2/pokemon/6"
128+
- name: Matching db result with the Pokemon Name
129+
selector: span[tracetest.span.type="database" name="create postgres.pokemon"]:first
130+
assertions:
131+
- attr:db.result contains "charizard"
132+
```
133+
134+
### GraphQL
135+
136+
```graphql title="resources/query.graphql"
137+
mutation import {
138+
importPokemon(id: 6) {
139+
id
140+
}
141+
}
142+
```
143+
144+
### GraphQL Schema
145+
146+
```graphql title="resources/schema.graphql"
147+
schema {
148+
query: Query
149+
mutation: Mutation
150+
}
151+
152+
type Pokemon {
153+
id: Int
154+
name: String!
155+
type: String!
156+
isFeatured: Boolean!
157+
imageUrl: String
158+
}
159+
160+
"The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1."
161+
scalar Int
162+
163+
"The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text."
164+
scalar String
165+
166+
"The `Boolean` scalar type represents `true` or `false`."
167+
scalar Boolean
168+
169+
type PokemonList {
170+
items: [Pokemon]
171+
totalCount: Int
172+
}
173+
174+
type ImportPokemon {
175+
id: Int!
176+
}
177+
178+
type Query {
179+
getPokemonList(where: String, skip: Int, take: Int): PokemonList
180+
}
181+
182+
type Mutation {
183+
createPokemon(name: String!, type: String!, isFeatured: Boolean!, imageUrl: String): Pokemon!
184+
importPokemon(id: Int!): ImportPokemon!
185+
}
186+
// ...See more in the schema.graphql file
187+
```
188+
189+
### Jaeger Tracing Backend
190+
191+
```yaml title="resources/datastore.yaml"
192+
type: DataStore
193+
spec:
194+
id: current
195+
name: jaeger
196+
type: jaeger
197+
default: true
198+
jaeger:
199+
endpoint: jaeger:16685
200+
headers:
201+
"": ""
202+
tls:
203+
insecure: true
204+
```
205+
206+
### The Apply Script
207+
208+
The apply script configures and provisions the resources in the Tracetest environment:
209+
210+
```bash title="resources/apply.sh"
211+
#!/bin/sh
212+
213+
set -e
214+
215+
TOKEN=$TRACETEST_API_KEY
216+
ENVIRONMENT_ID=$TRACETEST_ENVIRONMENT_ID
217+
218+
apply() {
219+
echo "Configuring TraceTest"
220+
tracetest configure --token $TOKEN --environment $ENVIRONMENT_ID
221+
222+
echo "Applying Resources"
223+
tracetest apply datastore -f /resources/datastore.yaml
224+
tracetest apply test -f /resources/test.yaml
225+
}
226+
227+
apply
228+
```
229+
230+
### The Run Script
231+
232+
The run script runs the test suite against the provisioned resources:
233+
234+
```bash title="resources/run.sh"
235+
#!/bin/sh
236+
237+
set -e
238+
239+
TOKEN=$TRACETEST_API_KEY
240+
ENVIRONMENT_ID=$TRACETEST_ENVIRONMENT_ID
241+
242+
run() {
243+
echo "Configuring Tracetest"
244+
tracetest configure --token $TOKEN --environment $ENVIRONMENT_ID
245+
246+
echo "Running Trace-Based Tests..."
247+
tracetest run test -f /resources/test.yaml
248+
}
249+
250+
run
251+
```
252+
253+
## Setting the Environment Variables
254+
255+
Copy the `.env.template` file to `.env` and add the Tracetest API token and agent tokens to the `TRACETEST_API_TOKEN` and `TRACETEST_ENVIRONMENT_ID` variables.
256+
257+
## Running the Full Example
258+
259+
Everything is automated for you to only run the following command:
260+
261+
```bash
262+
docker compose run tracetest-run
263+
```
264+
265+
This command will run the `apply.sh` script to provision the resources and the `run.sh` script to run the test suite.
266+
267+
## Finding the Results
268+
269+
The output from the Tracetest Engine script should be visible in the console log after running the test command.
270+
271+
```bash title=Output
272+
WARN[0000] /Users/oscar/Documents/kubeshop/t/examples/tracetest-jaeger-graphql-pokeshop/docker-compose.yaml: `version` is obsolete
273+
[+] Running 2/2
274+
✔ demo-api Pulled 0.9s
275+
✔ demo-worker Pulled 0.9s
276+
[+] Creating 10/9
277+
✔ Network tracetest-jaeger-graphql-pokeshop_default Created 0.0s
278+
✔ Container tracetest-jaeger-graphql-pokeshop-postgres-1 Created 0.1s
279+
✔ Container tracetest-jaeger-graphql-pokeshop-cache-1 Created 0.1s
280+
✔ Container tracetest-jaeger-graphql-pokeshop-tracetest-agent-1 Created 0.1s
281+
✔ Container tracetest-jaeger-graphql-pokeshop-queue-1 Created 0.1s
282+
✔ Container tracetest-jaeger-graphql-pokeshop-jaeger-1 Created 0.1s
283+
✔ Container tracetest-jaeger-graphql-pokeshop-demo-worker-1 Created 0.1s
284+
✔ Container tracetest-jaeger-graphql-pokeshop-otel-collector-1 Created 0.1s
285+
✔ Container tracetest-jaeger-graphql-pokeshop-demo-api-1 Created 0.1s
286+
✔ Container tracetest-jaeger-graphql-pokeshop-tracetest-apply-1 Created 0.0s
287+
[+] Running 9/9
288+
✔ Container tracetest-jaeger-graphql-pokeshop-cache-1 Healthy 10.5s
289+
✔ Container tracetest-jaeger-graphql-pokeshop-tracetest-agent-1 Started 0.3s
290+
✔ Container tracetest-jaeger-graphql-pokeshop-jaeger-1 Healthy 1.9s
291+
✔ Container tracetest-jaeger-graphql-pokeshop-postgres-1 Healthy 10.5s
292+
✔ Container tracetest-jaeger-graphql-pokeshop-queue-1 Healthy 10.5s
293+
✔ Container tracetest-jaeger-graphql-pokeshop-otel-collector-1 Started 0.1s
294+
✔ Container tracetest-jaeger-graphql-pokeshop-demo-worker-1 Started 0.1s
295+
✔ Container tracetest-jaeger-graphql-pokeshop-demo-api-1 Started 0.1s
296+
✔ Container tracetest-jaeger-graphql-pokeshop-tracetest-apply-1 Started 0.1s
297+
[+] Running 2/2
298+
✔ demo-api Pulled 0.8s
299+
✔ demo-worker Pulled 0.8s
300+
Configuring Tracetest
301+
SUCCESS Successfully configured Tracetest CLI
302+
Running Trace-Based Tests...
303+
✔ RunGroup: #US5klbqSR (https://app-stage.tracetest.io/organizations/ttorg_c71a6b53c3709e95/environments/ttenv_bcf29b43f06a12dc/run/US5klbqSR)
304+
Summary: 1 passed, 0 failed, 0 pending
305+
✔ Pokeshop - Import (https://app-stage.tracetest.io/organizations/ttorg_c71a6b53c3709e95/environments/ttenv_bcf29b43f06a12dc/test/re9XOxqSR/run/11/test) - trace id: 6facf84ee23757eda97930c16fd1d8f9
306+
✔ Import Pokemon Span Exists
307+
✔ Uses Correct PokemonId
308+
✔ Matching db result with the Pokemon Name
309+
```
310+
311+
## What's Next?
312+
313+
After running the test, you can click the run link, update the assertions, and run the scripts once more. This flow enables complete a trace-based TDD flow.
314+
315+
![assertions](../img/playwright-engine.gif)
316+
317+
## Learn More
318+
319+
Please visit our [examples in GitHub](https://github.com/kubeshop/tracetest/tree/main/examples) and join our [Slack Community](https://dub.sh/tracetest-community) for more info!

‎docs/docs/img/graphql-choose-trigger.png‎

215 KB
Loading

‎docs/docs/img/graphql-details-2.png‎

291 KB
Loading

‎docs/docs/img/graphql-details.png‎

234 KB
Loading

‎docs/docs/img/graphql-select-demo.png‎

281 KB
Loading

‎docs/docs/img/graphql-success.png‎

271 KB
Loading

0 commit comments

Comments
 (0)