Ohif Test Agent Skills by diattamo · Pull Request #5993 · OHIF/Viewers

diattamo · 2026-05-05T18:23:27Z

Summary

Adds an ohif-test-agent skill that teaches AI coding agents how to generate correct, runnable Playwright E2E tests for the OHIF Viewer using its custom fixture system, page objects, normalized WebGL viewport coordinates, and visual-regression conventions.

This PR landed iteratively. The original proposal published the skill under tests/ohif-test-agent/ and required each contributor to manually copy or symlink the folder into their agent client's skill directory. The current shape replaces that with a single canonical location that all major clients discover automatically, plus reviewer-driven hardening of the rules the skill enforces.

Changes

The skill is at .agents/skills/ohif-test-agent/ and contains:

SKILL.md — the entire behavior contract. Covers the environment model, test-authoring workflow, architecture (custom fixtures, page objects, normalized coordinates, WebGL viewport), study loading lifecycle, render-cycle waits vs sleeps, visual regression rules, Playwright config facts, canonical study UIDs, a hard rules list, and a mandatory pre-output self-check.
assets/spec-template.ts — a ready-to-copy test template with the correct imports, fixture destructuring, viewport interaction patterns, prompt handling, and assertion strategies.
references/patterns-by-feature.md — feature-area-indexed seed specs (length / freehand / SEG hydration / RTSTRUCT / TMTV / MPR / crosshairs / overlays / tag browser / etc.) plus the canonical study UID table.
references/page-objects.md — stable structural rules for the page object system; deliberately does not enumerate methods (the source is authoritative).
references/utilities.md — stable rules for tests/utils/ (barrel vs deep imports, the @playwright/test trap, object-param convention, visitStudy delays, checkForScreenshot direction).
references/failure-triage.md — categorize-then-debug guide for the failures the suite actually produces.

Discovery by agents: zero-config for three clients, one-liner for Claude Code

Client	Discovery	Setup required
GitHub Copilot / VS Code Agent	Scans `.agents/skills/` natively	none
OpenAI Codex (CLI / IDE per docs)	Scans `.agents/skills/` natively	none
Cursor	Scans `.agents/skills/` natively (per Cursor docs)	none
Claude Code	Scans only `.claude/skills/`	one-line symlink, documented in `AGENTS.md`

A root AGENTS.md was added in another commit. This has been updated to include a short "Skills" section describing the test skill and the Claude Code setup command (Windows variant included).

Working examples:

Client	Screenshot
gh Copilot
Cursor
Claude
Codex	`/<skill>` works after putting the skill files in a .cursor director similar to .claude. However, unlike claude, in the current .agents directory, it is discovered and used during agent task performance
(even) Antigravity

Test plan

Pull branch
Confirm .agents/skills/ohif-test-agent/SKILL.md exists
In VS Code with Copilot Agent: type /skills in chat and confirm ohif-test-agent is listed
In Cursor: type /skills in chat and confirm ohif-test-agent is listed
In Claude Code: run the documented ln -s once, then start a new session and confirm ohif-test-agent is in the discovered-skills list
Prompt: "Write an OHIF Playwright test for the Length tool" — verify the generated test
On Windows (if available): confirm core.symlinks=true allows the .claude/skills/ohif-test-agent symlink to materialize correctly

…t-interactions-rename-togglevisibility

…ing tests by removing redundant checks

updates to segment click logic address segment visibility tests comments simplify contour segment renaming tests

netlify · 2026-05-05T18:23:32Z

✅ Deploy Preview for ohif-dev canceled.

Name	Link
🔨 Latest commit	`f87a492`
🔍 Latest deploy log	https://app.netlify.com/projects/ohif-dev/deploys/6a077ddd57966500095843fe

jbocce · 2026-05-08T01:38:13Z

+
+1. Locate your Claude skills directory:
+   - Common location: `~/.claude/skills/`
+2. Copy this folder into that directory:


Is there any way for Claude to just find it in the worktree's directory? I apologize if this is a stupid question.

I updated the overall configuration to not have to perform this anymore.
But to answer your question. I have now made it so that claude finds it in the worktree. Just need to run a simple one line command.

jbocce · 2026-05-08T01:43:04Z

+
+## Codex setup
+
+Point your Codex runtime at `.github/agents/ohif-test-agent/`.


Do we need instructions prior to this for copying ohif-test-agent to the .github directory?

Not needed anymore

jbocce · 2026-05-08T01:44:33Z

+
+---
+
+## Codex setup


Can we add something for Cursor too?

Done. Cursor should now work out of the box.

jbocce · 2026-05-08T01:47:43Z

+| `1.3.6.1.4.1.14519.5.2.1.1706.8374.643249677828306008300337414785` | `viewer` | CT volume for 3D/MPR/crosshairs |
+| `1.3.6.1.4.1.14519.5.2.1.256467663913010332776401703474716742458` | `viewer` or `segmentation` | CT + SEG for labelmap tests |
+| `1.2.840.113619.2.290.3.3767434740.226.1600859119.501` | `viewer` / `segmentation` / `tmtv` | CT + RTSTRUCT + PET, used for contour and TMTV |
+| `1.3.6.1.4.1.14519.5.2.1.7695.4007.324475281161490036195179843543` | `viewer` | SR structured report |


We should consider adding more here.

jbocce · 2026-05-08T01:47:54Z

+| `1.2.840.113619.2.290.3.3767434740.226.1600859119.501` | `viewer` / `segmentation` / `tmtv` | CT + RTSTRUCT + PET, used for contour and TMTV |
+| `1.3.6.1.4.1.14519.5.2.1.7695.4007.324475281161490036195179843543` | `viewer` | SR structured report |
+
+Do not invent UIDs — they must exist on the e2e data server.


jbocce · 2026-05-08T01:51:41Z

+- **Object form** (preferred in newer specs): `checkForScreenshot({ page, screenshotPath, maxDiffPixelRatio?, threshold?, normalizedClip?, fullPage? })`
+- **Positional form** (still in use across older specs): `checkForScreenshot(page, locator, screenshotPath, ...)`
+
+The object form exposes tuning knobs the positional form doesn't — `maxDiffPixelRatio`, `threshold`, `normalizedClip`. For 3D content, bump `maxDiffPixelRatio` to around `0.04` because GPU rendering is noisier. Check the current signature in [tests/utils/checkForScreenshot.ts](tests/utils/checkForScreenshot.ts) (or wherever the barrel points) if something looks off.


I would rather AI not monkey with maxDiffPixelRatio. That should be something rarely touched.

Updated the instruction to not mess with this. I added instruction to have it reviewed instead.

jbocce · 2026-05-08T01:52:56Z

+
+### `checkForScreenshot` has two call forms
+
+- **Object form** (preferred in newer specs): `checkForScreenshot({ page, screenshotPath, maxDiffPixelRatio?, threshold?, normalizedClip?, fullPage? })`


The only reason object form is preferred because we want to stop taking the screenshot of the entire app and instead focus on the viewport or viewport grid. This should somehow be worked in here.

Updated this basically default to not using screenshots going forward. Take a look at the wording.

Copilot/Cursor/Codex now auto-discover via .agents/skills/. Claude Code needs a one-line symlink documented in AGENTS.md. .claude/ and .cursor/ added in .gitignore. Drops the obsolete AGENTS.md wrapper and instructions.md install guide; updates to tests/* markdown links in skill content

jbocce · 2026-05-15T14:35:15Z


+## Skills
+
+The `ohif-test-agent` skill (Playwright E2E test guidance) lives at `.agents/skills/ohif-test-agent/`. GitHub Copilot/VS Code Agent, OpenAI Codex, and Cursor scan `.agents/skills/` natively — no setup required. Claude Code scans only `.claude/skills/` so set up the symlink locally once after cloning:


Can this be tied into the preinstall.js file like what is done for (this) existing AGENTS.md file? I believe there is already a (similar) auto link for the AGENTS.md file in there.

Implemented so that it should work with
yarn install (or preinstall)

diattamo added 12 commits March 10, 2026 13:08

Added tests for segmenthe Rename interactions

7663236

feat(visibility): add segment visibility toggle tests

fc51b71

Address greptile code review finidings

e003e0f

Merge remote-tracking branch 'origin/master' into feat/contour-segmen…

f2b54e2

…t-interactions-rename-togglevisibility

refactor(tests): code review changes - simplify contour segment renam…

f3dbbea

…ing tests by removing redundant checks

refactor(tests): addres segment visibility tests comments

965e2d6

refactor(tests): updates to segment click logic

d584850

refactor(tests): Code review updates:

ee7770a

updates to segment click logic address segment visibility tests comments simplify contour segment renaming tests

refactor(tests): update segment click make sure click event is on title

8631974

Added agent files for testing

7a5f70d

Merge branch 'master' into feat/agentskills

23db944

Changes to agent files and move files to tests

b700178

jbocce self-requested a review May 6, 2026 15:41

jbocce reviewed May 8, 2026

View reviewed changes

diattamo added 3 commits May 14, 2026 12:20

Merge branch 'master' into feat/ohif-test-agent-skills

107597f

Updates to address code review comments

b62398d

diattamo requested a review from jbocce May 14, 2026 19:34

jbocce reviewed May 15, 2026

View reviewed changes

Added .claude configuration to preinstall.js

f87a492

diattamo requested a review from jbocce May 16, 2026 17:31


		## Codex setup

		Point your Codex runtime at `.github/agents/ohif-test-agent/`.


		### `checkForScreenshot` has two call forms

		- Object form (preferred in newer specs): `checkForScreenshot({ page, screenshotPath, maxDiffPixelRatio?, threshold?, normalizedClip?, fullPage? })`


		## Skills

		The `ohif-test-agent` skill (Playwright E2E test guidance) lives at `.agents/skills/ohif-test-agent/`. GitHub Copilot/VS Code Agent, OpenAI Codex, and Cursor scan `.agents/skills/` natively — no setup required. Claude Code scans only `.claude/skills/` so set up the symlink locally once after cloning:

Uh oh!

Conversation

diattamo commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Discovery by agents: zero-config for three clients, one-liner for Claude Code

Working examples:

Test plan

Uh oh!

netlify Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ohif-dev canceled.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

diattamo May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbocce May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

diattamo commented May 5, 2026 •

edited

Loading

netlify Bot commented May 5, 2026 •

edited

Loading

diattamo May 14, 2026 •

edited

Loading

jbocce May 8, 2026 •

edited

Loading