Skip to content

Commit 7debcdc

Browse files
pedjakclaude
pedjak
and
claude
committed
feat: replace asciinema with godog-based demo recording
Convert terminal demos from standalone shell scripts recorded via asciinema to Godog BDD scenarios that generate asciicast v2 files programmatically. This makes demos into verified tests that can never silently break while producing terminal recordings. The recording infrastructure captures kubectl commands and their stdout/stderr with real execution timing during @demo-tagged scenario execution. Per-step dedup handles polling transparently so only successful results appear in the recording. Step text is emitted as comments and commands are colored for readability. Demo scenarios: - ClusterCatalog Quickstart: queries the operatorhubio catalog API - SingleNamespace Install Mode: installs mariadb-operator with a separate watch namespace, verifies rolebindings - OwnNamespace Install Mode: installs mariadb-operator with watch namespace equal to install namespace - Webhook Support: installs telegraf-operator, verifies mutating webhook injects sidecar container into test pod Not converted (no matching demo scenarios): - Synthetic User Permissions: feature gate disabled in experimental - Helm Chart Support: blocked by OCPBUGS-95281 The update-demos Makefile target now builds OLM from source using the experimental e2e infrastructure, deploys with all feature gates and operatorhubio catalog, runs demo scenarios, converts recordings to SVG via svg-term-cli, and tears down the cluster. Demo recordings are embedded in docs via the mkdocs-asciinema-player plugin and served from GitHub Pages, removing the dependency on asciinema.org for hosting recordings. Demo scenarios are excluded from regular e2e test runs via ~@demo filter. CI workflow (update-demos.yaml): - On PR: generates demos, uploads asciicast and SVG files as job artifacts - On merge to main: generates demos, deploys docs with updated recordings via make deploy-docs Old demo shell scripts, the asciinema generate-asciidemo.sh wrapper, and hack/demo/ resource files have been removed. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent d0252d4 commit 7debcdc

38 files changed

Lines changed: 920 additions & 892 deletions

‎.github/workflows/update-demos.yaml‎

Lines changed: 28 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,52 @@
11
name: update-demos
22

33
on:
4-
schedule:
5-
- cron: '0 3 * * *' # Runs every day at 03:00 UTC
64
workflow_dispatch:
75
push:
6+
branches: [main]
87
paths:
98
- 'api/*'
109
- 'config/*'
11-
- 'hack/demo/*'
10+
- 'test/e2e/features/demos.feature'
11+
- 'test/e2e/steps/demo_steps.go'
12+
- 'test/e2e/steps/asciicast_*.go'
1213
- '.github/workflows/update-demos.yaml'
1314
pull_request:
1415
paths:
1516
- 'api/*'
1617
- 'config/*'
17-
- 'hack/demo/*'
18+
- 'test/e2e/features/demos.feature'
19+
- 'test/e2e/steps/demo_steps.go'
20+
- 'test/e2e/steps/asciicast_*.go'
1821
- '.github/workflows/update-demos.yaml'
19-
22+
2023
jobs:
21-
demo:
24+
generate-demos:
2225
runs-on: ubuntu-latest
26+
permissions:
27+
contents: ${{ github.event_name == 'push' && 'write' || 'read' }}
2328
env:
2429
TERM: linux
2530
steps:
26-
- run: sudo apt update && sudo apt install -y asciinema curl
2731
- uses: actions/checkout@v7.0.0
2832
- uses: actions/setup-go@v6.4.0
2933
with:
3034
go-version-file: "go.mod"
31-
- name: Run Demo Update
32-
run: |
33-
env -i \
34-
HOME="$HOME" \
35-
PATH="$PATH" \
36-
TERM="xterm-256color" \
37-
SHELL="/bin/bash" \
38-
make update-demos
35+
- uses: actions/setup-python@v6.2.0
36+
with:
37+
python-version: 3.x
38+
cache: pip
39+
- name: Generate demo recordings
40+
run: make update-demos
41+
42+
- uses: actions/upload-artifact@v7
43+
if: always()
44+
with:
45+
name: demo-recordings
46+
path: |
47+
docs/demos/*.cast
48+
docs/demos/*.svg
3949
50+
- name: Deploy docs with updated demos
51+
if: github.event_name == 'push'
52+
run: make deploy-docs

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,9 @@ vendor/
5454
# documentation website asset folder
5555
site
5656

57+
# generated demo asciicast recordings
58+
docs/demos/
59+
5760
.tiltbuild/
5861
.catalogd-tmp/
5962
.vscode

‎Makefile‎

Lines changed: 29 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -413,11 +413,11 @@ ifeq ($(strip $(GODOG_ARGS)),)
413413
set +e; \
414414
KUBECONFIG=$(E2E_KUBECONFIG) \
415415
PROMETHEUS_URL=http://localhost:$$E2E_PROMETHEUS_PORT \
416-
go test -count=1 -v ./test/e2e/features_test.go -timeout $(or $(E2E_TIMEOUT),20m) -args --godog.tags="~@Serial" --godog.concurrency=100; \
416+
go test -count=1 -v ./test/e2e/features_test.go -timeout $(or $(E2E_TIMEOUT),20m) -args --godog.tags="~@Serial && ~@demo" --godog.concurrency=100; \
417417
parallelExit=$$?; \
418418
KUBECONFIG=$(E2E_KUBECONFIG) \
419419
PROMETHEUS_URL=http://localhost:$$E2E_PROMETHEUS_PORT \
420-
go test -count=1 -v ./test/e2e/features_test.go -timeout $(or $(E2E_TIMEOUT),20m) -args --godog.tags="@Serial" --godog.concurrency=1; \
420+
go test -count=1 -v ./test/e2e/features_test.go -timeout $(or $(E2E_TIMEOUT),20m) -args --godog.tags="@Serial && ~@demo" --godog.concurrency=1; \
421421
serialExit=$$?; \
422422
if [[ $$parallelExit -ne 0 ]] || [[ $$serialExit -ne 0 ]]; then \
423423
echo "e2e tests failed: parallel=$$parallelExit serial=$$serialExit"; \
@@ -693,13 +693,33 @@ deploy-docs: venv
693693
. $(VENV)/activate; \
694694
mkdocs gh-deploy --force --strict
695695

696-
# The demo script requires to install asciinema with: brew install asciinema to run on mac os envs.
697-
# Please ensure that all demos are named with the demo name and the suffix -demo-script.sh
698-
.PHONY: update-demos #EXHELP Validate demo recordings.
699-
update-demos:
700-
@for script in hack/demo/*-demo-script.sh; do \
701-
nm=$$(basename $$script -script.sh); \
702-
./hack/demo/generate-asciidemo.sh -n $$nm $$(basename $$script); \
696+
DEMO_OUTPUT_DIR ?= $(ROOT_DIR)/docs/demos
697+
698+
.PHONY: update-demos
699+
update-demos: SOURCE_MANIFEST := $(EXPERIMENTAL_E2E_MANIFEST)
700+
update-demos: export MANIFEST := $(EXPERIMENTAL_RELEASE_MANIFEST)
701+
update-demos: export DEFAULT_CATALOG := $(CATALOGS_MANIFEST)
702+
update-demos: export INSTALL_DEFAULT_CATALOGS := true
703+
update-demos: export CATALOG_WAIT_TIMEOUT := 5m
704+
update-demos: wait-operator-controller-experimental-e2e demo-e2e demo-svg experimental-e2e-teardown #EXHELP Record demo scenarios as asciicast and SVG files.
705+
706+
.PHONY: demo-e2e
707+
demo-e2e:
708+
@command -v curl >/dev/null 2>&1 || { echo "Error: curl not found in PATH."; exit 1; }
709+
@command -v jq >/dev/null 2>&1 || { echo "Error: jq not found in PATH."; exit 1; }
710+
@mkdir -p $(DEMO_OUTPUT_DIR)
711+
KUBECONFIG=$(KUBECONFIG_DIR)/operator-controller-experimental-e2e.kubeconfig \
712+
DEMO_OUTPUT_DIR=$(DEMO_OUTPUT_DIR) go test -count=1 -v ./test/e2e/features_test.go -timeout 30m \
713+
-args --godog.tags="@demo" --godog.concurrency=1
714+
715+
.PHONY: demo-svg
716+
demo-svg: #EXHELP Convert asciicast recordings to SVG.
717+
@command -v docker >/dev/null 2>&1 || { echo "Error: docker not found in PATH."; exit 1; }
718+
@for cast in $(DEMO_OUTPUT_DIR)/*.cast; do \
719+
svg=$${cast%.cast}.svg; \
720+
echo "Converting $$(basename $$cast) -> $$(basename $$svg)"; \
721+
docker run --rm -v $(DEMO_OUTPUT_DIR):/data node:alpine \
722+
npx --yes svg-term-cli --in /data/$$(basename $$cast) --out /data/$$(basename $$svg) --window; \
703723
done
704724

705725
include Makefile.venv

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ To get started with OLM v1, please see our [Getting Started](https://operator-fr
3434

3535
### Quickstart DEMO
3636

37-
[![asciicast](https://asciinema.org/a/682344.svg)](https://asciinema.org/a/682344)
37+
[![ClusterCatalog Demo](https://operator-framework.github.io/operator-controller/demos/clustercatalog-quickstart.svg)](https://operator-framework.github.io/operator-controller/)
3838

3939
### ClusterCatalog Quickstart Steps
4040

‎docs/draft/howto/enable-webhook-support.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,4 +52,8 @@ There's no change in the installation flow. Just install a bundle containing web
5252
As there is no difference in usage or experience between the CertManager and Openshift-ServiceCA variants, only
5353
the cert-manager variant is demoed.
5454

55-
[![asciicast](https://asciinema.org/a/GyjsB129GkUadeuxFhNuG4FcS.svg)](https://asciinema.org/a/GyjsB129GkUadeuxFhNuG4FcS)
55+
```asciinema-player
56+
{
57+
"file": "../../../demos/webhook-support.cast"
58+
}
59+
```

‎docs/draft/howto/single-ownnamespace-install.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,19 @@ include *installModes*.
2525

2626
### SingleNamespace Install
2727

28-
[![SingleNamespace Install Demo](https://asciinema.org/a/w1IW0xWi1S9cKQFb9jnR07mgh.svg)](https://asciinema.org/a/w1IW0xWi1S9cKQFb9jnR07mgh)
28+
```asciinema-player
29+
{
30+
"file": "../../../demos/singlenamespace-install-mode.cast"
31+
}
32+
```
2933

3034
### OwnNamespace Install
3135

32-
[![OwnNamespace Install Demo](https://asciinema.org/a/Rxx6WUwAU016bXFDW74XLcM5i.svg)](https://asciinema.org/a/Rxx6WUwAU016bXFDW74XLcM5i)
36+
```asciinema-player
37+
{
38+
"file": "../../../demos/ownnamespace-install-mode.cast"
39+
}
40+
```
3341

3442
## Enabling the Feature-Gate
3543

‎hack/demo/catalogd-demo-script.sh‎

Lines changed: 0 additions & 38 deletions
This file was deleted.

‎hack/demo/catalogd-metas-demo-script.sh‎

Lines changed: 0 additions & 44 deletions
This file was deleted.

‎hack/demo/generate-asciidemo.sh‎

Lines changed: 0 additions & 91 deletions
This file was deleted.

0 commit comments

Comments
 (0)