chore(examples): Tracetest Playwright Engine Trigger (#3937)

* chore(examples): Tracetest Playwright Engine Trigger

* chore(docs): Adding Tracetest Playwright Engine Recipe

* chore(docs): Adding Tracetest Playwright Engine Recipe

docs/docs/examples-tutorials/recipes.mdx

@@ -18,6 +18,12 @@ breadcrumb_label: Nothing
 
 Recipes are short, self-contained, guides for getting started with building popular use cases using Tracetest!
 
+## Tracetest Triggers
+
+These guides show how to get the best of your instrumentation using the native Tracetest Triggers.
+
+- [True End-To-End Trace-Based Tests with the Tracetest Playwright Engine](/examples-tutorials/recipes/running-tests-with-tracetest-playwright-engine)
+
 ## Automation & Provisioning
 
 These guides show how to automate and provision Tracetest.

docs/docs/examples-tutorials/recipes/running-tests-with-tracetest-playwright-engine.mdx

@@ -0,0 +1,278 @@
+---
+id: running-tests-with-tracetest-playwright-engine
+title: True End-To-End Trace-Based Tests with the Tracetest Playwright Engine Trigger
+description: Quickstart on how to crete True End-To-End Trace-Based Tests with the Tracetest Playwright Engine Trigger
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - end-to-end testing
+  - tracetest
+  - playwright
+  - trace-based-testing
+  - trigger
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
+
+:::info Version Compatibility
+The features described here are compatible with the [Tracetest CLI v1.4.1](https://github.com/kubeshop/tracetest/releases/tag/v1.4.1) and above.
+:::
+
+:::note
+[Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-playwright-engine)
+:::
+
+[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.
+[Playwright](https://playwright.dev/) is an open-source automation framework developed by Microsoft that enables cross-browser automation for web applications. It provides a set of APIs and libraries for automating interactions with web browsers such as Chrome, Firefox, and Microsoft Edge.
+
+## Why is this important?
+
+The Tracetest Playwright Engine trigger enables you to combine the power of end-to-end tests with trace-based testing to easily capture a full distributed trace from your OpenTelemetry instrumented front-end and back-end system.
+
+By creating a Tracetest Playwright Engine 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.
+
+Another big benefit of using traces as test specs is that you can:
+
+- Get faster MTTR for failing performance tests
+- Assert against the Playwright test execution and the system under test
+- Validate functionality of other parts of your system that may be broken, even when end-to-end tests are passing
+
+## Requirements
+
+**Tracetest Account**:
+
+- Sign up to [`app.tracetest.io`](https://app.tracetest.io) or follow the [get started](/getting-started/installation) docs.
+- Create an [environment](/concepts/environments).
+- Create an [environment token](/concepts/environment-tokens) with **admin role**.
+- Copy the environment id to your clipboard.
+
+**Docker**: Have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed on your machine.
+
+## Run This Example
+
+The example below is provided as part of the Tracetest GitHub repo. You can download and run the example by following these steps:
+Clone the Tracetest project and go to the Privisioning Developer Environment with CLI example directory:
+
+```bash
+git clone https://github.com/kubeshop/tracetest
+cd tracetest/examples/tracetest-playwright-engine
+```
+
+Follow these instructions to run the example:
+
+1. Log into the [Tracetest app](https://app.tracetest.io/).
+2. Copy the `.env.template` file to `.env`.
+3. Fill out the [TRACETEST_API_TOKEN](https://docs.tracetest.io/concepts/environment-tokens) and [TRACETEST_ENVIRONMENT_ID](https://docs.tracetest.io/concepts/agent) details by editing your `.env` file. You can find these values in the Settings area for your environment.
+4. Run `docker compose run tracetest-run`.
+5. Follow the link in the terminal with the results to view the test run.
+
+## Project Structure
+
+The project structure for running Tracetest Playwright Engine tests is as follows:
+
+```bash
+.env.template
+.gitignore
+.Dockerfile
+collector.config.yaml
+docker-compose.yaml
+/resources
+  apply.sh
+  datastore.yaml
+  import-pokemon.yaml
+  run.sh
+  script.js
+```
+
+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.
+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.
+
+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.
+
+## Provisioned Resources
+
+The example provisions the following resources:
+
+### Import Pokemon Test
+
+```yaml title="resources/import-pokemon.yaml"
+type: Test
+spec:
+  id: import-pokemon
+  name: Import Pokemon
+  trigger:
+    type: playwrightengine
+    playwrightEngine:
+      target: http://api:8081
+      script: ./script.js
+      method: importPokemon
+  specs:
+    - selector: span[tracetest.span.type="general" name="documentLoad"]
+      name: Document Load Should be fast
+      assertions:
+        - attr:tracetest.span.duration < 500ms
+    - selector: span[tracetest.span.type="http" http.scheme="http"]
+      name: All HTTP request should return 200
+      assertions:
+        - attr:http.status_code = 200
+    - selector: span[tracetest.span.type="messaging" name="queue.synchronizePokemon
+        process" messaging.system="rabbitmq"
+        messaging.destination="queue.synchronizePokemon"
+        messaging.operation="process"]
+      name: The worker should be processed
+      assertions:
+        - attr:tracetest.selected_spans.count = 1
+    - selector: span[tracetest.span.type="database"]
+      name: "All Database Spans: Processing time is less than 100ms"
+      assertions:
+        - attr:tracetest.span.duration  <  250ms
+```
+
+### Playwright Script
+
+```javascript title="resources/script.js"
+const { expect } = require("@playwright/test");
+
+async function importPokemon(page) {
+  expect(await page.getByText("Pokeshop")).toBeTruthy();
+
+  await page.click("text=Import");
+  await page.getByLabel("ID").fill("143");
+
+  await Promise.all([
+    page.waitForResponse((resp) => resp.url().includes("/pokemon/import") && resp.status() === 200),
+    page.getByRole("button", { name: "OK", exact: true }).click(),
+  ]);
+}
+
+module.exports = { importPokemon };
+```
+
+### Jaeger Tracing Backend
+
+```yaml title="resources/datastore.yaml"
+type: DataStore
+spec:
+  id: current
+  name: jaeger
+  type: jaeger
+  default: true
+  jaeger:
+    endpoint: jaeger:16685
+    headers:
+      "": ""
+    tls:
+      insecure: true
+```
+
+### The Apply Script
+
+The apply script configures and provisions the resources in the Tracetest environment:
+
+```bash title="resources/apply.sh"
+#!/bin/sh
+
+set -e
+
+TOKEN=$TRACETEST_API_KEY
+ENVIRONMENT_ID=$TRACETEST_ENVIRONMENT_ID
+
+apply() {
+  echo "Configuring TraceTest"
+  tracetest configure --token $TOKEN --environment $ENVIRONMENT_ID
+
+  echo "Applying Resources"
+  tracetest apply datastore -f /resources/datastore.yaml
+  tracetest apply test -f /resources/import-pokemon.yaml
+}
+
+apply
+```
+
+### The Run Script
+
+The run script runs the test suite against the provisioned resources:
+
+```bash title="resources/run.sh"
+#!/bin/sh
+
+set -e
+
+TOKEN=$TRACETEST_API_KEY
+ENVIRONMENT_ID=$TRACETEST_ENVIRONMENT_ID
+
+run() {
+  echo "Configuring Tracetest"
+  tracetest configure --token $TOKEN --environment $ENVIRONMENT_ID
+
+  echo "Running Trace-Based Tests..."
+  tracetest run test -f /resources/import-pokemon.yaml
+}
+
+run
+```
+
+## Setting the Environment Variables
+
+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.
+
+## Running the Full Example
+
+Everything is automated for you to only run the following command:
+
+```bash
+docker compose run tracetest-run
+```
+
+This command will run the `apply.sh` script to provision the resources and the `run.sh` script to run the test suite.
+
+## Finding the Results
+
+The output from the Tracetest Engine script should be visible in the console log after running the test command.
+
+```bash title=Output
+docker compose run tracetest-run
+
+[+] Running 2/2
+ ✔ worker Pulled                                                                                                                                                  0.9s
+ ✔ api Pulled                                                                                                                                                     1.2s
+[+] Creating 6/0
+ ✔ Container tracetest-playwright-engine-tracetest-agent-1  Running                                                                                               0.0s
+ ✔ Container tracetest-playwright-engine-otel-collector-1   Running                                                                                               0.0s
+ ✔ Container tracetest-playwright-engine-jaeger-1           Running                                                                                               0.0s
+ ✔ Container tracetest-playwright-engine-postgres-1         Running                                                                                               0.0s
+ ✔ Container tracetest-playwright-engine-queue-1            Running                                                                                               0.0s
+ ✔ Container tracetest-playwright-engine-cache-1            Running                                                                                               0.0s
+[+] Running 6/6
+ ✔ Container tracetest-playwright-engine-queue-1            Healthy                                                                                               0.5s
+ ✔ Container tracetest-playwright-engine-postgres-1         Healthy                                                                                               0.5s
+ ✔ Container tracetest-playwright-engine-cache-1            Healthy                                                                                               0.5s
+ ✔ Container tracetest-playwright-engine-worker-1           Started                                                                                               0.1s
+ ✔ Container tracetest-playwright-engine-api-1              Healthy                                                                                               1.7s
+ ✔ Container tracetest-playwright-engine-tracetest-apply-1  Started                                                                                               0.1s
+[+] Running 2/2
+ ✔ api Pulled                                                                                                                                                     1.0s
+ ✔ worker Pulled                                                                                                                                                  1.0s
+Configuring Tracetest
+ SUCCESS  Successfully configured Tracetest CLI
+Running Trace-Based Tests...
+✔ RunGroup: #2XdxnzuIR (https://app.tracetest.io/organizations/ttorg_ced62e34638d965e/environments/ttenv_b42fa137465c6e04/run/2XdxnzuIR)
+ Summary: 1 passed, 0 failed, 0 pending
+  ✔ Import Pokemon (https://app.tracetest.io/organizations/ttorg_ced62e34638d965e/environments/ttenv_b42fa137465c6e04/test/import-pokemon/run/19/test) - trace id: 3d5cf7f8d3c78b2bc49eaa355809dc0e
+	✔ Document Load Should be fast
+	✔ All HTTP request should return 200
+	✔ The worker should be processed
+	✔ All Database Spans: Processing time is less than 100ms
+```
+
+## What's Next?
+
+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.
+
+![assertions](../img/playwright-engine.gif)
+
+## Learn More
+
+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/sidebars.js

@@ -121,6 +121,17 @@ const sidebars = {
       },
       label: "Recipes",
       items: [
+        {
+          type: "category",
+          label: "Tracetest Triggers",
+          items: [
+            {
+              type: "doc",
+              id: "examples-tutorials/recipes/running-tests-with-tracetest-playwright-engine",
+              label: "True End-To-End Trace-Based Tests with the Tracetest Playwright Engine",
+            },
+          ],
+        },
         {
           type: "category",
           label: "Streams and Message Queues",

examples/tracetest-playwright-engine/.env.template

@@ -0,0 +1,2 @@
+TRACETEST_API_TOKEN=
+TRACETEST_ENVIRONMENT_ID=

examples/tracetest-playwright-engine/.gitignore

@@ -0,0 +1,13 @@
+node_modules
+.vscode
+
+node_modules/
+api/.build/
+.idea/
+.DS_Store
+.env
+
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

examples/tracetest-playwright-engine/Dockerfile

@@ -0,0 +1,11 @@
+FROM alpine
+
+WORKDIR /app
+ARG TRACETEST_IMAGE_VERSION=v1.4.0
+
+RUN apk --update add bash jq curl
+RUN curl -L https://raw.githubusercontent.com/kubeshop/tracetest/main/install-cli.sh | bash -s -- $TRACETEST_IMAGE_VERSION
+
+WORKDIR /resources
+
+ENTRYPOINT ["echo", "Tracetest CLI installed"]

examples/tracetest-playwright-engine/README.md

@@ -0,0 +1,15 @@
+# Tracetest Playwright Engine Trigger
+
+This repository's objective is to show how you can configure trace-based tests using the Tracetest Playwright Engine Trigger.
+
+## Documentation Recipe
+
+This example is part of the official Tracetest docs and can be found by following this [link](https://docs.tracetest.io/examples-tutorials/recipes/running-tests-with-tracetest-playwright-engine).
+
+## Steps
+
+1. Copy the `.env.template` file to `.env`.
+2. Log into the [Tracetest app](https://app.tracetest.io/).
+3. Fill out the [TRACETEST_API_TOKEN](https://docs.tracetest.io/concepts/environment-tokens) with an admin role token and the [TRACETEST_ENVIRONMENT_ID](https://docs.tracetest.io/concepts/environments) with the id of your environment.
+4. Run `docker compose run tracetest-run`.
+5. Follow the links in the log to view the test runs programmatically created by your Playwright script.

examples/tracetest-playwright-engine/collector.config.yaml

@@ -0,0 +1,27 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+      http:
+        cors:
+          allowed_origins:
+            - "http://*"
+            - "https://*"
+
+processors:
+  batch:
+
+exporters:
+  logging:
+    loglevel: debug
+  jaeger:
+    endpoint: jaeger:14250
+    tls:
+      insecure: true
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [logging, jaeger]