feat: gcx as the assertion engine

.github/renovate-tracked-deps.json

@@ -16,11 +16,6 @@
         "mise"
       ]
     },
-    ".github/workflows/integration_test.yml": {
-      "regex": [
-        "mise"
-      ]
-    },
     ".github/workflows/lint.yml": {
       "regex": [
         "mise"
@@ -33,6 +28,7 @@
     },
     "go.mod": {
       "gomod": [
+        "github.com/BurntSushi/toml",
         "github.com/cenkalti/backoff/v5",
         "github.com/cespare/xxhash/v2",
         "github.com/davecgh/go-spew",
@@ -83,6 +79,8 @@
         "golangci-lint",
         "goreleaser",
         "hadolint",
+        "k3d",
+        "kubectl",
         "lychee",
         "node",
         "npm:renovate",

.github/workflows/e2e_test.yml

@@ -1,12 +1,11 @@
----
-name: End-to-end tests
+name: E2E tests
 
 on: [pull_request]
 
 permissions: {}
 
 jobs:
-  test:
+  build-e2e-tools:
     runs-on: ubuntu-24.04
     steps:
       - name: Check out
@@ -17,5 +16,65 @@ jobs:
         with:
           version: v2026.7.0
           sha256: 0744cb3c303baf0d308ff7b112ed41f22abb6029cb5644fd3a8ce74b29f16a68
-      - name: Run end-to-end test
-        run: mise run e2e-test
+      - name: Build e2e tools
+        run: ./scripts/build-local-tools.sh "$PWD/.e2e-tools/bin"
+      - name: Upload e2e tools
+        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.6.2
+        with:
+          name: e2e-tools
+          path: .e2e-tools/bin
+          if-no-files-found: error
+
+  test-e2e:
+    needs: build-e2e-tools
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [core, compose, remote, k3d-fail, k3d-smoke]
+    steps:
+      - name: Check out
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+      - uses: jdx/mise-action@e6a8b3978addb5a52f2b4cd9d91eafa7f0ab959d # v4.2.0
+        with:
+          version: v2026.7.0
+          sha256: 0744cb3c303baf0d308ff7b112ed41f22abb6029cb5644fd3a8ce74b29f16a68
+      - name: Download e2e tools
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        with:
+          name: e2e-tools
+          path: .e2e-tools/bin
+      - name: Restore e2e tool permissions
+        run: chmod +x .e2e-tools/bin/oats .e2e-tools/bin/gcx
+      - name: Run ${{ matrix.shard }} e2e tests
+        # OATS_E2E_FILTER is not part of the matrix to avoid that it shows up in the gh action (too long)
+        run: |
+          start_ts="$(date +%s)"
+          case "${{ matrix.shard }}" in
+            core)
+              export OATS_E2E_FILTER="-fixture/"
+              ;;
+            compose)
+              export OATS_E2E_FILTER="fixture/compose"
+              ;;
+            remote)
+              export OATS_E2E_FILTER="fixture/remote"
+              ;;
+            k3d-fail)
+              export OATS_E2E_FILTER="fixture/k3d-fail"
+              ;;
+            k3d-smoke)
+              export OATS_E2E_FILTER="fixture/k3d-smoke"
+              ;;
+            *)
+              echo "unknown e2e shard: ${{ matrix.shard }}" >&2
+              exit 1
+              ;;
+          esac
+          export OATS_E2E_BIN_DIR="$PWD/.e2e-tools/bin"
+          echo "e2e timing: shard=${{ matrix.shard }} filter=${OATS_E2E_FILTER} bin_dir=${OATS_E2E_BIN_DIR}"
+          mise run e2e-test
+          end_ts="$(date +%s)"
+          echo "e2e timing: shard=${{ matrix.shard }} total=$((end_ts-start_ts))s"

AGENTS.md

@@ -9,7 +9,7 @@ OpenTelemetry written in Go. It enables full round-trip testing from
 instrumented applications to the observability stack (LGTM: Loki, Grafana,
 Tempo, Prometheus, Mimir, OpenTelemetry Collector).
 
-Test cases are defined in YAML files with `oats-schema-version: 2` and can
+Test cases are defined in YAML files with `oats-schema-version: 3` and can
 validate traces (TraceQL), logs (LogQL), metrics (PromQL), and profiles
 (Pyroscope queries) using Docker Compose or Kubernetes backends.
 
@@ -19,13 +19,10 @@ validate traces (TraceQL), logs (LogQL), metrics (PromQL), and profiles
 # Build
 mise run build
 
-# Run unit tests
+# Run non-e2e tests
 mise run test
 
-# Run integration tests (requires Docker)
-mise run integration-test
-
-# Run end-to-end tests
+# Run e2e tests
 mise run e2e-test
 ```
 
@@ -51,7 +48,8 @@ EditorConfig rules live in `.editorconfig`.
 
 ### Package Organization
 
-- **`main.go`** — CLI entry point. Parses flags, discovers YAML test files, runs them sequentially
+- **`main.go`** — Root `oats` CLI entry point
+- **`internal/cli/`** — The gcx-driven CLI implementation used by the root binary
 - **`model/`** — Core data models (`TestCaseDefinition`, expected signals)
 - **`yaml/`** — Test case parsing, execution, signal-specific assertions
   (`runner.go`, `traces.go`, `metrics.go`, `logs.go`, `profiles.go`)
@@ -61,31 +59,22 @@ EditorConfig rules live in `.editorconfig`.
 
 ### Test Case Schema
 
-Required fields:
-
-- `oats-schema-version: 2` (must be present in all test files)
-- `oats-template: true` (for template files used in `include`)
-
-Core sections: `include`, `docker-compose`, `kubernetes`, `matrix`, `input`, `interval`, `expected`
-
-File discovery scans for `.yaml`/`.yml` files containing
-`oats-schema-version`. Files with `oats-template: true` are skipped as entry
-points. `.oatsignore` causes a directory to be ignored.
+Current user-facing syntax is documented in `README.md`. Legacy yaml parsing
+still exists in-package for migration support, but the repo's CLI surface is
+the current `oats.toml` + case-yaml flow.
 
 ## CLI Usage
 
 ```bash
-# Run specific test file
-oats /path/to/test.yaml
-
-# Scan directory for all tests
-oats /path/to/tests/
+# Print a plan
+oats --config oats.toml --list
 
 # With flags
-oats -timeout 1m -lgtm-version latest /path/to/test.yaml
+oats --config oats.toml --timeout 1m
 ```
 
-Key flags: `-timeout` (default 30s), `-lgtm-version` (default "latest"), `-manual-debug` (keep containers running)
+Key flags: `--config`, `--suite`, `--tags`, `--timeout`, `--interval`,
+`--absent-timeout`, `--parallel`, `--gcx`, `--gcx-context`, `--version`
 
 ## Code Conventions
 
@@ -98,11 +87,10 @@ Key flags: `-timeout` (default 30s), `-lgtm-version` (default "latest"), `-manua
 ## Testing
 
 - Unit tests: `mise run test`
-- Integration tests require `INTEGRATION_TESTS=true` env var
 - Uses gomega for assertions, stretchr/testify for test utilities
 
 ## CI
 
 - Lint on PRs (`mise run lint`), build on PRs (`mise run build`), tests on PRs (`mise run test`)
-- Integration tests and e2e tests in separate workflows
+- E2E tests in a separate workflow
 - Linting via flint

CURRENT.md

@@ -0,0 +1 @@
+# Current OATS docs now live in [README.md](README.md)