Skip to content

Commit b270749

Browse files
DiljohnSinghDiljohnSingh
authored
Merge branch 'main' into feat/Carousel-slides-props
2 parents 9c89bf9 + e5374cc commit b270749

16 files changed

Lines changed: 810 additions & 30 deletions

File tree

‎.claude/commands/mendix/e2e-spec.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
You are helping the developer write or improve Playwright e2e specs for a Mendix pluggable widget in the web-widgets monorepo.
2+
3+
**Read first**: `docs/requirements/e2e-test-guidelines.md` — owns all rules for imports, assertions, locators, navigation, and snapshots. Do not duplicate them here.
4+
5+
## Context
6+
7+
- Specs live at: `packages/pluggableWidgets/<widget>/e2e/*.spec.js`
8+
- Playwright strict mode is ON
9+
10+
> `<widget>` throughout this document is the package folder name, e.g. `badge-web`, `datagrid-web`.
11+
12+
## Discovering selectors and navigation from the test project
13+
14+
Before writing selectors, look up the actual widget names and menu labels in the `.mpr`:
15+
16+
```bash
17+
# Full overview: modules, pages, entities, navigation menu labels
18+
bash automation/mxcli/mx-testproject.sh inspect badge-web # replace with actual widget name
19+
20+
# Widget structure of a specific page (reveals .mx-name-* values)
21+
bash automation/mxcli/mx-testproject.sh exec <widget> "DESCRIBE PAGE <Module>.<PageName>"
22+
23+
# List pages if you don't know the page name
24+
bash automation/mxcli/mx-testproject.sh list-pages <widget>
25+
26+
# Search for a widget name across all project strings
27+
bash automation/mxcli/mx-testproject.sh search <widget> 'keyword'
28+
```
29+
30+
The `inspect` output includes `DESCRIBE NAVIGATION Responsive` at the end — use those exact strings in `page.getByRole("menuitem", { name: "..." })`.
31+
32+
## Spec file split
33+
34+
Standard naming convention per widget:
35+
36+
- `<widget>.spec.js` — core rendering and data binding
37+
- `onClick.spec.js` — microflow, nanoflow, keyboard accessibility
38+
- `dataTypes.spec.js` — each supported Mendix attribute type
39+
- `layouts.spec.js` — widget inside list view, tab, data view, listen-to-grid
40+
41+
## Running tests
42+
43+
```bash
44+
# Full CI run (Docker):
45+
pnpm --filter @mendix/badge-web run e2e # replace with actual widget name
46+
47+
# Skip re-downloading the test project (useful when iterating locally):
48+
pnpm --filter @mendix/<widget> run e2e --no-setup-project
49+
50+
# Skip re-downloading and rebuilding (fastest iteration; requires local test project files):
51+
pnpm --filter @mendix/<widget> run e2e --no-setup-project --no-update-project
52+
```
53+
54+
⚠️ Pass flags directly — do NOT use `pnpm run e2e -- --no-setup-project`. The `--` separator causes yargs-parser to ignore the flags.
55+
56+
> Use `--no-setup-project --no-update-project` when you have the test project files locally and want to commit them to the `testProjects` repository after confirming tests pass.
57+
58+
## Checklist
59+
60+
- [ ] Import from `@mendix/run-e2e/fixtures` — NOT `@playwright/test`
61+
- [ ] No manual `afterEach` logout — fixture handles it
62+
- [ ] No `waitForLoadState("networkidle")` — prohibited, see guidelines
63+
- [ ] No locator matches multiple elements without `.first()` or a compound selector
64+
- [ ] No assertions on Atlas design classes
65+
- [ ] All tests pass in CI (`pnpm run e2e`)

‎.claude/commands/mendix/e2e-workflow.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
You are orchestrating the full e2e development workflow for a Mendix pluggable widget in the web-widgets monorepo.
2+
3+
Widget name passed by user: $ARGUMENTS
4+
5+
If no widget name is provided, ask the user which widget they are working on (e.g., `badge-web`, `datagrid-web`).
6+
7+
## Prerequisites
8+
9+
- `automation/tools/mxcli` must exist. If missing, run: `bash automation/mxcli/setup.sh`
10+
- The `.mpr` test project must be **closed in Studio Pro** before any mxcli edits. Check with:
11+
```bash
12+
ls packages/pluggableWidgets/<widget>/tests/testProject/.mendix-cache/lock 2>/dev/null \
13+
&& echo "⚠️ Studio Pro lock file present — close the project first" \
14+
|| echo "OK — no lock file"
15+
```
16+
- Docker must be running for the full CI e2e run
17+
18+
---
19+
20+
## Phase 1 — Download and inspect the test project
21+
22+
Download the test project (if not already present):
23+
24+
```bash
25+
pnpm --filter @mendix/<widget> run e2edev --setup-project
26+
```
27+
28+
If this fails with `404 Not Found` / `Cannot find test project in GitHub repository`, the branch does not exist yet in `mendix/testProjects`. In that case:
29+
30+
1. Copy an existing chart/widget MPR as a base (e.g. from `column-chart-web/tests/testProject/`).
31+
2. Place it at `packages/pluggableWidgets/<widget>/tests/testProject/<WidgetName>.mpr`.
32+
3. Copy the `widgets/`, `deployment/`, `theme/`, and `themesource/` folders from the same source.
33+
4. Replace the source widget's `.mpk` in `widgets/` with the new widget's built `.mpk` (run `pnpm --filter @mendix/<widget> run release` first).
34+
5. Adapt the domain model and microflows via mxcli (see `mendix:edit-test-project`).
35+
6. After Studio Pro has opened the MPR and registered the new widget type, push a new branch `<widget>` to `mendix/testProjects` so CI can download it.
36+
37+
Then inspect:
38+
39+
```bash
40+
bash automation/mxcli/mx-testproject.sh inspect <widget>
41+
```
42+
43+
This shows modules, pages, entities, and navigation menu labels in one call. For a specific page's widget structure:
44+
45+
```bash
46+
bash automation/mxcli/mx-testproject.sh exec <widget> "DESCRIBE PAGE <Module>.<PageName>"
47+
```
48+
49+
> **Note**: `DESCRIBE PAGE` may show an empty body for pages that only contain pluggable widgets. Use `automation/tools/mxcli bson dump -p <MPR> --type page --object <Module>.<Page>` and grep for widget names to verify content. See `mendix:edit-test-project` for details.
50+
51+
**Output**: map of modules, pages, navigation labels, and `.mx-name-*` widget names.
52+
53+
---
54+
55+
## Phase 1b — Baseline lint (recommended before edits)
56+
57+
```bash
58+
bash automation/mxcli/mx-testproject.sh lint <widget>
59+
```
60+
61+
Note any pre-existing violations — re-run after edits to confirm you introduced none.
62+
63+
---
64+
65+
## Phase 2 — Edit the test project (only if needed)
66+
67+
Only needed when a new page or entity is required. See `mendix:edit-test-project` for full MDL guidance and the validate → diff → apply safety flow.
68+
69+
Key rules:
70+
71+
- **Never** use `CREATE OR MODIFY PAGE Module.ExistingPage {}` — wipes all widget content
72+
- Always include `Layout: Atlas_Core.Atlas_Default` in `CREATE PAGE`
73+
- Always `GRANT VIEW ON PAGE` after creating a page
74+
- Confirm with the user before any `.mpr` changes
75+
76+
After edits: remind the user to reopen Studio Pro and click **Synchronize App Directory**.
77+
78+
---
79+
80+
## Phase 3 — Write or update the Playwright spec
81+
82+
Follow `mendix:e2e-spec` for selector discovery via mxcli and spec file naming. Follow `docs/requirements/e2e-test-guidelines.md` for all Playwright rules (imports, assertions, navigation, snapshots).
83+
84+
Spec files live at: `packages/pluggableWidgets/<widget>/e2e/*.spec.js`
85+
86+
---
87+
88+
## Phase 4 — Build the widget MPK
89+
90+
```bash
91+
pnpm --filter @mendix/<widget> run release
92+
```
93+
94+
---
95+
96+
## Phase 5 — Run the e2e suite
97+
98+
```bash
99+
# Full CI run (Docker):
100+
pnpm --filter @mendix/<widget> run e2e
101+
102+
# Skip re-downloading the test project:
103+
pnpm --filter @mendix/<widget> run e2e --no-setup-project
104+
105+
# Skip re-downloading and rebuilding:
106+
pnpm --filter @mendix/<widget> run e2e --no-setup-project --no-update-project
107+
```
108+
109+
⚠️ Pass flags directly — do NOT use `pnpm run e2e -- --no-setup-project`. The `--` separator causes yargs-parser to ignore the flags.
110+
111+
If tests fail:
112+
113+
- Strict-mode errors → add `.first()` or a compound selector
114+
- Session errors → confirm import is from `@mendix/run-e2e/fixtures`
115+
- Timeout errors → use `waitForMendixApp(page)` or `waitForDataReady(page)` from `@mendix/run-e2e/mendix-helpers`
116+
117+
---
118+
119+
## Phase 6 — Visual validation with Playwright MCP
120+
121+
After the suite passes, do a live smoke check against the running app (`http://localhost:3001`, credentials `MxAdmin` / `1`):
122+
123+
```
124+
mcp__plugin_playwright_playwright__browser_navigate
125+
mcp__plugin_playwright_playwright__browser_snapshot
126+
mcp__plugin_playwright_playwright__browser_take_screenshot
127+
mcp__plugin_playwright_playwright__browser_click
128+
mcp__plugin_playwright_playwright__browser_type
129+
mcp__plugin_playwright_playwright__browser_fill_form
130+
mcp__plugin_playwright_playwright__browser_wait_for
131+
mcp__plugin_playwright_playwright__browser_close
132+
```
133+
134+
---
135+
136+
## Done checklist
137+
138+
- [ ] All existing tests still pass (no regressions)
139+
- [ ] New tests pass in CI
140+
- [ ] Visual snapshot updated if needed (`--update-snapshots`)
141+
- [ ] `.mpr` changes committed if any were made
142+
- [ ] Lint re-run after MPR edits confirms no new violations

‎.claude/commands/mendix/edit-test-project.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
You are helping the developer edit a Mendix test project (.mpr file) to support a new or updated Playwright e2e test in the web-widgets monorepo.
2+
3+
## Context
4+
5+
- Test projects live at: `packages/pluggableWidgets/<widget>/tests/testProject/<Name>.mpr`
6+
- `mxcli` reads/writes `.mpr` files via MDL (Mendix Definition Language)
7+
- Binary: `automation/tools/mxcli` — gitignored, install with `bash automation/mxcli/setup.sh`
8+
- The `.mpr` **must be closed in Studio Pro** before mxcli can edit it
9+
- mxcli is **alpha software** — ensure `.mendix-cache/backup/AppBackup.mpr` exists before bulk edits
10+
- For Playwright rules that new pages must satisfy, see `mendix:e2e-spec` and `docs/requirements/e2e-test-guidelines.md`
11+
12+
---
13+
14+
## Step 1 — Identify widget and goal
15+
16+
Ask the user (or infer from context): which widget, and what scenario requires a test project change?
17+
18+
## Step 2 — Check prerequisites
19+
20+
```bash
21+
[[ -x automation/tools/mxcli ]] && echo "OK" || bash automation/mxcli/setup.sh
22+
ls packages/pluggableWidgets/<widget>/tests/testProject/*.mpr | grep -v backup
23+
```
24+
25+
Verify Studio Pro is **not** holding the project open before any mxcli writes:
26+
27+
```bash
28+
ls packages/pluggableWidgets/<widget>/tests/testProject/.mendix-cache/lock 2>/dev/null \
29+
&& echo "⚠️ Studio Pro lock file present — close the project first" \
30+
|| echo "OK — no lock file"
31+
```
32+
33+
## Step 3 — Inspect current state
34+
35+
```bash
36+
# Full overview: modules, pages, entities, navigation
37+
bash automation/mxcli/mx-testproject.sh inspect <widget>
38+
39+
# Targeted queries:
40+
automation/tools/mxcli -p <MPR_PATH> -c "SHOW PAGES IN <Module>"
41+
automation/tools/mxcli -p <MPR_PATH> -c "SHOW ENTITIES IN <Module>"
42+
automation/tools/mxcli -p <MPR_PATH> -c "SHOW MICROFLOWS IN <Module>"
43+
automation/tools/mxcli -p <MPR_PATH> -c "DESCRIBE PAGE <Module>.<PageName>"
44+
bash automation/mxcli/mx-testproject.sh search <widget> 'keyword'
45+
```
46+
47+
> **`DESCRIBE PAGE` caveat**: pages containing only pluggable widgets (no built-in widgets like `DATAVIEW`, `LAYOUTGRID`, etc.) may render as an empty body even when widget content exists in the MPR. Use `automation/tools/mxcli bson dump -p <MPR> --type page --object <Module>.<Page>` and grep for widget names to verify content was written.
48+
49+
> **`SEARCH` quoting**: use single-quoted strings — `SEARCH 'keyword'`, not `SEARCH "keyword"`. Double quotes cause a parse error.
50+
51+
> **`SHOW ROLES IN <Module>`** — this MDL statement does not exist. Use `SHOW MODULES` output to see module source; roles are returned inline. To query roles programmatically use the catalog: `SELECT Name FROM CATALOG.USER_ROLES`.
52+
53+
Run a baseline lint before editing:
54+
55+
```bash
56+
bash automation/mxcli/mx-testproject.sh lint <widget>
57+
```
58+
59+
## Step 4 — Plan and execute MDL changes
60+
61+
#### ⚠️ `CREATE OR MODIFY PAGE ... {}` wipes page content
62+
63+
Never use it on a page that already has widgets — the empty body replaces all content. Restore from `tests/testProject/.mendix-cache/backup/AppBackup.mpr` if this happens.
64+
65+
#### Safety flow: validate → diff → apply
66+
67+
```bash
68+
# 1. Validate MDL syntax and references:
69+
bash automation/mxcli/mx-testproject.sh check <widget> changes.mdl
70+
71+
# 2. Preview as a diff (no writes):
72+
bash automation/mxcli/mx-testproject.sh diff <widget> changes.mdl
73+
74+
# 3. Apply:
75+
bash automation/mxcli/mx-testproject.sh exec <widget> "$(cat changes.mdl)"
76+
```
77+
78+
#### Creating a new page
79+
80+
```
81+
CREATE PAGE Module.PageName (
82+
Title: 'Page Title',
83+
Layout: Atlas_Core.Atlas_Default
84+
)
85+
```
86+
87+
Always include `Layout: Atlas_Core.Atlas_Default` — omitting it causes mxbuild to fail with exit code 3.
88+
89+
After creating, grant page access or mxbuild fails:
90+
91+
```bash
92+
automation/tools/mxcli -p <MPR_PATH> -c "GRANT VIEW ON PAGE <Module>.<PageName> TO <Module>.<RoleName>"
93+
```
94+
95+
#### Navigating to pages from Playwright
96+
97+
For **existing pages** with widget content — use menu traversal (no mxcli changes needed). Get labels from `inspect` output:
98+
99+
```js
100+
test.beforeEach(async ({ page }) => {
101+
await page.goto("/");
102+
await page.getByRole("menuitem", { name: "Menu Label" }).click();
103+
await page.getByRole("menuitem", { name: "Page Label" }).click();
104+
});
105+
```
106+
107+
For **brand-new empty pages** created by mxcli, the URL is auto-generated from the page name. Discover it with:
108+
109+
```bash
110+
automation/tools/mxcli -p <MPR_PATH> -c "DESCRIBE PAGE <Module>.<PageName>"
111+
# Look for the `url:` field in the output, e.g. url: 'my-page-name'
112+
```
113+
114+
Then navigate directly in the spec:
115+
116+
```js
117+
await page.goto("/p/my-page-name");
118+
```
119+
120+
## Step 5 — Rebuild and validate
121+
122+
Continue with `mendix:e2e-workflow` from Phase 4 (build → run → validate).
123+
124+
---
125+
126+
## MDL Quick Reference
127+
128+
| Goal | MDL / Command |
129+
| -------------------------- | ----------------------------------------------------------------------------- |
130+
| List modules | `SHOW MODULES` |
131+
| List pages | `SHOW PAGES IN Module` |
132+
| List entities | `SHOW ENTITIES IN Module` |
133+
| List microflows | `SHOW MICROFLOWS IN Module` |
134+
| List nanoflows | `SHOW NANOFLOWS IN Module` |
135+
| Describe page widgets | `DESCRIBE PAGE Module.PageName` |
136+
| Describe navigation menu | `DESCRIBE NAVIGATION Responsive` |
137+
| Search project strings | `SEARCH 'keyword'` |
138+
| Show callers of microflow | `SHOW CALLERS OF Module.MicroflowName` |
139+
| Show callers (transitive) | `SHOW CALLERS OF Module.MicroflowName TRANSITIVE` |
140+
| Show references to element | `SHOW REFERENCES TO Module.ElementName` |
141+
| Show impact of element | `SHOW IMPACT OF Module.ElementName` |
142+
| Show context for AI | `SHOW CONTEXT OF Module.ElementName DEPTH 3` |
143+
| Create page | `CREATE PAGE Module.Name (Title: 'Title', Layout: Atlas_Core.Atlas_Default)` |
144+
| Grant page access | `GRANT VIEW ON PAGE Module.Page TO Module.Role` |
145+
| Create entity | `CREATE ENTITY Module.Name (Attr: String(200))` |
146+
| Discover widgets by type | `SHOW WIDGETS WHERE widgettype LIKE '%combobox%'` |
147+
| Bulk-update widget props | `UPDATE WIDGETS SET 'showLabel' = false WHERE widgettype LIKE '%X%' DRY RUN` |
148+
| Populate catalog tables | `REFRESH CATALOG FULL` |
149+
| Catalog SQL query | `SELECT Name, ActivityCount FROM CATALOG.MICROFLOWS WHERE ActivityCount > 10` |
150+
| Validate MDL syntax + refs | `mxcli check changes.mdl -p app.mpr --references` |
151+
| Preview changes as diff | `mxcli diff -p app.mpr changes.mdl` |
152+
153+
## Pluggable widget limitations
154+
155+
mxcli can only create pluggable widget instances (`PLUGGABLEWIDGET '...' name (...)`) when the MPR **already contains an existing instance** of that widget type (Studio Pro registers the BSON template the first time the widget is imported). If no instance exists yet, mxcli fails with `template not found: <widgetname>`.
156+
157+
**Workaround for a brand-new widget in a new test project:**
158+
159+
1. Create the page with **named containers** and placeholder `DYNAMICTEXT` widgets (these are built-in and always work).
160+
2. Open the `.mpr` in Studio Pro — it will register the widget type from the `.mpk` in `tests/testProject/widgets/`.
161+
3. Inside each container, replace the placeholder with the actual pluggable widget instance.
162+
4. After Studio Pro saves, run `automation/tools/mxcli widget init -p <MPR>` to cache the widget definition.
163+
5. Future `PLUGGABLEWIDGET` statements for that widget will then work via mxcli.
164+
165+
**Widget management commands:**
166+
167+
```bash
168+
# Register widget definitions from all .mpk files in the project's widgets/ dir
169+
automation/tools/mxcli widget init -p <MPR_PATH>
170+
171+
# Extract a .def.json skeleton from a specific .mpk (does not bootstrap the BSON template)
172+
automation/tools/mxcli widget extract --mpk <path>.mpk
173+
174+
# List all registered widget definitions and their MDL keywords
175+
automation/tools/mxcli widget list -p <MPR_PATH>
176+
177+
# Generate MDL syntax docs for a specific widget
178+
automation/tools/mxcli widget docs -p <MPR_PATH> <mdl-name>
179+
```
180+
181+
The `widget list` output shows the MDL keyword (e.g. `bubblechart`) needed in `PLUGGABLEWIDGET` blocks. The keyword lookup is case-insensitive but the widget ID string is exact.
182+
183+
## Warnings
184+
185+
- Do NOT run mxcli while Studio Pro has the project open — check for the lock file (Step 2)
186+
- New pages need `GRANT VIEW ON PAGE` — missing it causes mxbuild exit code 3
187+
- `automation/tools/mxcli` is gitignored — run `bash automation/mxcli/setup.sh` on first checkout
188+
- `PLUGGABLEWIDGET` requires an existing instance in the MPR — use named containers as placeholders for brand-new widgets and configure them in Studio Pro first
189+
- Test project changes may require updating the `testProjects` repo branch for CI — flag this to the user

0 commit comments

Comments
 (0)