CEDAR Tutorial

A scripted, repeatable tutorial for the CEDAR Workbench. A Playwright step-driver walks the CEDAR UI, generating consistent screenshots that a single-page tutorial document references by stable filenames.

The tutorial itself walks the core CEDAR workflow end to end — designing a template, filling it out to produce a metadata instance, building a richer template that binds fields to a controlled ontology (a branch of DOID) and external authorities (ORCID, ROR), publishing a versioned release, and sharing a record on the public web via OpenView. The point of scripting it is that every screenshot regenerates identically when the UI or the content changes, so the tutorial never drifts out of sync with the live product.

Architecture

Two artifacts, connected by a filename contract:

1. runner/ — a Playwright script with one small function per tutorial step, each screenshotting the meaningful UI states as it goes (e.g. shot(page, "07-empty-form")). Deterministic and re-runnable. See runner/README.md for details.
2. tutorial/ — the single-page tutorial (tutorial.md) whose figures reference the screenshot filenames in tutorial/img/.

When the UI changes: fix the affected step in the runner, wipe tutorial/img/, rerun. The tutorial prose only changes when the flow changes.

Repo layout

tutorial/tutorial.md    the tutorial page (GitHub- and MkDocs-compatible Markdown)
tutorial/img/           generated screenshots (the filename contract)
runner/                 Playwright step-driver (config, steps, orchestrator, auth, cleanup)
tools/preview/          local live-reload preview page
preview.sh              serve the tutorial locally for debugging
publish.sh              copy the tutorial into a cedar-mkdocs checkout

Previewing while debugging

No MkDocs needed:

./preview.sh            # serves http://localhost:8765/tools/preview/ and opens it

The page live-reloads: edit tutorial/tutorial.md (or regenerate screenshots) and it refreshes itself within a second, preserving your scroll position.

Publishing to the manual

./publish.sh            # copies into ../cedar-mkdocs (or $CEDAR_MKDOCS)

publish.sh copies the tutorial into your local clone of the cedar-mkdocs repo (by default ../cedar-mkdocs, or wherever $CEDAR_MKDOCS points). It doesn't publish anything itself. All it does is copy two things:

• tutorial.md → docs/user-guide/tutorial/index.md (the tutorial's page in the manual)
• everything in tutorial/img/ → a sibling img/ folder next to that page

The tutorial refers to its screenshots by relative paths like img/07-empty-form.png. Because they land in that sibling img/ folder, the image links keep working as-is, with no paths to edit.

To actually publish, switch to your cedar-mkdocs clone, review the changes with git diff, then commit and push. The docs site rebuilds from there. The first time only, also make the page appear in the site's navigation menu by adding user-guide/tutorial/index.md to mkdocs.yml.

Tutorial flow

1. Create a folder
2. Create a basic study template; add fields
3. View the generated form and populate it (create metadata)
4. Create a richer template: controlled terms and external-authority fields
5. Populate it
6. Version the template
7. Enable OpenView; show the OpenView rendering

Run lifecycle

Every run is self-contained and leaves the account pristine:

• Setup: create a run folder (Tutorial Run <run-id>/); all artifacts are created inside it
• Steps: execute in order, screenshotting along the way
• Teardown: delete all artifacts — instances before templates (a published template can't be deleted while an instance of it exists) — then delete the run folder

If CEDAR's backend transiently refuses a delete, teardown leaves the run folder and prints its name; node cleanup.mjs sweeps any leftover Tutorial Run … folders on a later pass.

Consistency between runs

• Fixed Playwright viewport (1120×1000, deviceScaleFactor: 2), colorScheme: 'light' — the narrow width keeps the UI large in the frame (a browser-zoom effect)
• CSS animations disabled before screenshots
• All content (names, values, ontology, version) comes from runner/config.mjs, so it's identical every run; only the run-folder name (in a few breadcrumbs) varies
• Always generate on the same platform (font rendering differs across OSes)

Run & iterate

cd runner
npm install && npx playwright install chromium
node auth.mjs               # one-time: log in; saves storageState.json (git-ignored)
node run.mjs                # wipe screenshots, run all steps, tear down
node run.mjs --no-teardown  # keep the run folder/artifacts to inspect
HEADED=1 node run.mjs       # watch it in a real browser
node cleanup.mjs            # delete leftover "Tutorial Run …" folders

On failure the runner saves failures/FAILED-<step>.png plus console output, and leaves the run folder for inspection. No credentials live in the repo — auth is via storageState.json.