Skip to content

docs(#3333): warn about runOnce key collisions in multi-project workspaces #3334

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fullsend-ai-coder wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(#3333): warn about runOnce key collisions in multi-project workspaces #3334

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,29 @@ test.beforeAll(async ({ rhdh }) => {
- Nesting is safe — `deploy()` uses `runOnce` internally, wrapping it in an outer `runOnce` is harmless.
- Uses file-based flags in `/tmp/` scoped to the Playwright runner process. Flags reset automatically between test runs.

**Key collision trap in multi-project workspaces:** When the same spec file runs in multiple Playwright projects (e.g. `bulk-import` and `bulk-import-app-next`), a literal `runOnce` key creates a collision — the first project's flag file satisfies the second project's check, silently skipping its `configure()` + `deploy()` call. The second project's namespace never gets an RHDH deployment, and all its tests fail with misleading UI errors (e.g. "missing heading") with no indication that the deployment was skipped.

Always scope `runOnce` keys by namespace to avoid this:

```typescript
// ✅ Correct — namespace-scoped key, safe for multi-project runs
await test.runOnce(
`my-workspace-setup-${rhdh.deploymentConfig.namespace}`,
async () => {
await rhdh.configure({ auth: "keycloak" });
await rhdh.deploy();
}
);

// ❌ Wrong — literal key collides across projects sharing this spec
await test.runOnce("my-workspace-setup", async () => {
await rhdh.configure({ auth: "keycloak" });
await rhdh.deploy();
});
```

This mirrors what `deploy()` does internally (`deploy-${namespace}`). See PR [#3318](https://github.com/redhat-developer/rhdh-plugin-export-overlays/pull/3318) for the case study where this caused 9 silent test failures.

### RHDH Deployment Flow

`rhdh.deploy()` performs these steps:
Expand Down
Loading