docs(tutorials): user + admin walkthroughs with durable screenshot capture by rubenvdlinde · Pull Request #132 · ConductionNL/mydash

rubenvdlinde · 2026-05-06T06:42:11Z

Summary

15 step-by-step tutorial pages plus a durable Playwright capture spec to keep the screenshots fresh.

10 end-user tutorials covering the everyday workflows
5 admin tutorials covering org-wide configuration
1 Playwright spec (tests/e2e/docs-screenshots.spec.ts) under a new docs-capture project that drives every flow and writes PNGs into docs/screenshots/tutorials/{user,admin}/

End-user track (`docs/tutorials/user/`)

#	Page
01	Open MyDash for the first time
02	Create a new dashboard
03	Add a widget
04	Reposition & resize widgets
05	Edit widget content & style
06	Remove a widget
07	Set a default dashboard (the ★ marker from PR #130)
08	Bookmark or share a dashboard URL (deep-linking from PR #131)
09	Switch between dashboards
10	Rename or delete a dashboard

Admin track (`docs/tutorials/admin/`)

#	Page
01	Enable / disable personal dashboards globally
02	Create an admin template dashboard
03	Mark a group's default dashboard
04	Restrict widgets per role (RFP allow-list)
05	Bulk operations on dashboards

Each page: Goal → Prerequisites → numbered Steps with inline screenshots → Verification → Common-issues table → Reference cross-links into features/*.md.

Screenshot capture

npx playwright test --project docs-capture drives the entire flow matrix and writes screenshots in one programmatic pass. The spec is excluded from the default e2e run so PR pipelines don't reshoot. Three baseline screenshots (first launch, sidebar open, cog menu) are checked in for reference; the rest are populated by the spec.

Build

Docusaurus is configured to warn (not error) on broken markdown images so the build succeeds before the capture spec has run. docusaurus build produces both en and nl outputs cleanly.

Test plan

docusaurus build clean (zero errors, only deferred-image warnings + 3 unrelated cross-link warnings now fixed)
All 15 tutorial pages have well-formed frontmatter and valid internal links
Run npx playwright test --project docs-capture against a seeded local instance to refresh all screenshots
Manual review of the rendered docs site (npx docusaurus start) — verify navigation, sidebar order, image references resolve

Notes

I deliberately did not invent a "share dashboards" UI — the share flow is documented as the existing path: admin marks a group default → users in that group see it under DEFAULT.
Three new-feature screenshots (★ marker, deep-link URL bar, default-bundle on a fresh dashboard) require development-branch mydash deployed; the local env still serves an older feature branch. Reshoot via the capture spec once development is rolled out.

…pture 10 end-user tutorials (`docs/tutorials/user/`) cover the everyday workflows — first launch, create dashboard, add/edit/remove widgets, reposition & resize on the grid, set a default with the ★ marker, deep-link a dashboard via slug-chain URL, switch dashboards, and rename or delete. 5 admin tutorials (`docs/tutorials/admin/`) cover the personal-dashboards toggle, admin templates, group defaults, role-based widget restrictions, and bulk operations. Each page follows: Goal → Prerequisites → numbered Steps with inline screenshots → Verification → Common issues, and cross-links into the existing `features/*.md` reference docs. A new Playwright project `docs-capture` (in `playwright.config.ts`) runs the dedicated `tests/e2e/docs-screenshots.spec.ts` to drive every flow and write fresh PNGs into `docs/screenshots/tutorials/{user,admin}/`. The spec is excluded from the default test run so PR pipelines don't reshoot screenshots; opt in with: npx playwright test --project docs-capture Three baseline screenshots (first launch, sidebar, cog menu) are included in this commit; the rest are populated by the capture spec. Docusaurus is configured to warn — not error — on broken markdown images, so the build succeeds even before the capture runs.

github-actions · 2026-05-06T06:45:21Z

Quality Report — ConductionNL/mydash @ `6f12293`

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 100/100
npm			✅	✅ 501/501
PHPUnit					✅
Newman					✅
Playwright					⏭️

Coverage: 90.7% (127/140 statements)

Quality workflow — 2026-05-06 06:45 UTC

Download the full PDF report from the workflow artifacts.

…ion.nl Updates the three places that pin the docs domain: the GitHub Pages CNAME static file, the Docusaurus url config, and the deploy workflow's `cname:` input. Existing in-app Documentation links (`DOCS_URL` in SidebarFooter.vue, `doc-url` in AdminSettings.vue) still point at mydash.app — leave those for a follow-up so the app-code change can be reviewed separately from the docs-infra change.

github-actions · 2026-05-06T06:49:33Z

Quality Report — ConductionNL/mydash @ `b766354`

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 100/100
npm			✅	✅ 501/501
PHPUnit					✅
Newman					✅
Playwright					⏭️

Coverage: 90.7% (127/140 statements)

Quality workflow — 2026-05-06 06:49 UTC

Download the full PDF report from the workflow artifacts.

…ixes First end-to-end run of `--project docs-capture` against the local Nextcloud instance. 6/15 tests pass cleanly; the rest hit selector misses on UI markup that drifted since the spec was authored. Failures are non-fatal (each test re-navigates from `/apps/mydash/`) so the run captures everything reachable up to the first miss in each flow. Captured: - user track: 13 PNGs (U1 first launch + U2 add button + create modal, U3 edit-mode + widget picker, U4 edit mode + drag + reflow, U7 default marker, U8 url bar, U9 after switch) - admin track: 3 PNGs (A2 templates list + create modal, A3 group cog) Spec changes: - `mode: 'default'` instead of serial — selector misses no longer cascade to abort the suite. - U2 create-dashboard form: hooked on placeholder text from `DashboardConfigModal.vue` (`"My dashboard"`, `"What is this dashboard for?"`) instead of the non-existent `name=` attributes. - `playwright.config.ts`: per-project `testIgnore` so the chromium regression project skips the capture spec while the docs-capture project picks it up. The previous root-level ignore was shadowing the project's testMatch. Remaining selector misses live in the spec for follow-up: - U3 picker → form → added (the `Text` button selector misses its actual NcActions label) - U4 resize handle (`.ui-resizable-handle.ui-resizable-se` doesn't match the actual GridStack drag-handle class) - U5/U6 context menu (`.widget-context-menu` vs the actual class) - U7 fallback marker (depends on PR #130 deployment) - U8 deep-link landing (depends on PR #131 deployment) - U10 dashboard-config modal selector - A1 / A4 / A5 admin pages — most need an admin nav probe Each remaining failure dropped a `test-results/<test>/test-failed-1.png` that shows the page state at the moment of failure — those are useful debugging starting points.

github-actions · 2026-05-06T07:04:14Z

Quality Report — ConductionNL/mydash @ `39fde97`

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 100/100
npm			✅	✅ 501/501
PHPUnit					✅
Newman					✅
Playwright					⏭️

Coverage: 90.7% (127/140 statements)

Quality workflow — 2026-05-06 07:04 UTC

Download the full PDF report from the workflow artifacts.

Selector misses on the first capture-spec run came from depending on visible label text (which i18n shifts), CSS classes (refactor magnets), and aria-labels that map to multiple elements. Switched the high-traffic selectors to `data-testid` so the spec survives copy edits, class renames, and Vue refactors. Twelve new test ids: - `DashboardConfigModal.vue` — dashboard-name-input, dashboard-description-input, dashboard-save-button, dashboard-delete-button - `DashboardRowActions.vue` — cog-edit-dashboard, cog-dashboard-config, cog-add-widget, cog-set-default, cog-delete - `WidgetContextMenu.vue` — widget-context-menu (container), ctx-edit, ctx-remove, ctx-cancel - `AddWidgetModal.vue` — add-widget-save The `data-testid` attributes are inert in production renders (no behaviour, no styling) and don't change any user-facing markup. Specs target them via `[data-testid="…"]` selectors. Updated `tests/e2e/docs-screenshots.spec.ts` (U2, U3, U5, U6, U7, U10) to use the new ids. The remaining failure modes are env-specific (PR #130/#131 deployment for the ★ marker and deep-link landing) rather than selector brittleness. Note: the live env serves the previously-built bundle, so reshooting requires `npm run build` (or removing `js/mydash-main.js` so the playwright globalSetup auto-rebuilds) before `npx playwright test --project docs-capture`.

github-actions · 2026-05-06T07:12:46Z

Quality Report — ConductionNL/mydash @ `56aaea6`

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 100/100
npm			✅	✅ 501/501
PHPUnit					✅
Newman					✅
Playwright					⏭️

Coverage: 90.7% (127/140 statements)

Quality workflow — 2026-05-06 07:12 UTC

Download the full PDF report from the workflow artifacts.

The admin track flows previously hooked on \`role=tab\` (the page is a single scroll, not tabbed) and on visible button labels (\`Create role\` when the actual label is \`Add role permission\`). Replaced with stable \`data-testid\` selectors on the section anchors and primary action buttons: - \`AdminSettings.vue\` — admin-default-settings, admin-allow-user-dashboards, admin-templates-section, admin-create-template, admin-bulk-section, admin-roles-section - \`RolePermissionsSection.vue\` — admin-add-role Spec updates (A1, A2, A4, A5): - A1 toggle: scroll the Default settings section into view, then zoom on the allow-user-dashboards switch. Skip the user-disabled capture to avoid leaving the test instance with personal dashboards off. - A2 templates: testid for the Create template button and the section scroll target. Edit-template selector kept permissive — that path is not the focus. - A4 roles: drop the role=tab assumption; scroll the section into view and use the new admin-add-role testid for the modal trigger. - A5 bulk: scroll-into-view via admin-bulk-section testid; filter/move/confirm sub-shots stay manual until the bulk component itself gets a deeper test-id pass. DashboardBulkOperations.vue already carries \`data-test=*\` attributes that the spec can hook into in a follow-up — left untouched here so the existing convention isn't churned.

github-actions · 2026-05-06T07:24:10Z

Quality Report — ConductionNL/mydash @ `0f6a9ad`

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 100/100
npm			✅	✅ 501/501
PHPUnit					✅
Newman					✅
Playwright					⏭️

Coverage: 90.7% (127/140 statements)

Quality workflow — 2026-05-06 07:24 UTC

Download the full PDF report from the workflow artifacts.

Final round of test-id instrumentation. Eight new ids close the remaining selector misses for U3 (add widget), U4 (reposition/resize), U5 (style editor), and U6 (remove via context menu). - \`AddWidgetModal.vue\` — widget-type-select on the type \`<select>\` itself (specs use \`selectOption()\` instead of guessing button names), plus widget-type-option-\${type} on each \`<option>\` for explicit per-type selection. - \`WidgetWrapper.vue\` — widget-placement-\${id} on the per-placement root, widget-edit-cog on the per-placement edit button. The id suffix lets specs uniquely target a placement when more than one exists; selectors using the \`^=\` prefix match any placement when identity doesn't matter. - \`WidgetStyleEditor.vue\` — widget-style-editor on the modal body, widget-style-save on the primary action. Spec updates: - U3: switched from \`getByRole('button', { name: /^Text$/ })\` (which never matched — the picker is a \`<select>\`, not buttons) to \`selectOption('text')\` against the new widget-type-select. - U4: drag and resize targets switched to widget-placement-* prefix selectors. The mouse-down y offset is now +30px from the top of the placement to land on the title bar regardless of widget content. - U5: dropped the never-existed \`Style\` context-menu entry; the style editor opens via the per-placement edit cog (only visible in edit mode), so the test enters edit mode first via cog-edit-dashboard. - U6: removed brittle \`.grid-stack-item, .widget-wrapper\` fallback; uses widget-placement-* prefix. Docusaurus build still clean (en + nl). Total stable test-ids in PR #132: 28 across 8 components.

github-actions · 2026-05-06T07:49:42Z

Quality Report — ConductionNL/mydash @ `4bc4e51`

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 100/100
npm			✅	✅ 501/501
PHPUnit					✅
Newman					✅
Playwright					⏭️

Coverage: 90.7% (127/140 statements)

Quality workflow — 2026-05-06 07:49 UTC

Download the full PDF report from the workflow artifacts.

…nted bundle Built the worktree bundle (with the 28 new test-ids) and swapped it into the live nextcloud instance to validate the capture spec end-to-end. Bundle restored to the original after the run; live mydash unchanged. 9 of 15 capture tests passed cleanly, producing 26 unique PNGs: User track (passing): U1 first launch (3), U3 add widget (4 — picker + form + added now work via widget-type-select), U9 switch dashboards, U10 rename/delete (config modal + delete confirm now work via dashboard-name-input + dashboard-delete-button). Admin track (passing): A1 toggle (2), A2 templates (3), A3 group cog, A4 roles section + create modal, A5 bulk panel. Failures fall into three buckets: 1. Env-dependent (PR #131 server routes not deployed): - U7 fallback marker / U8 deep-link landed — the JS pushes URL state but the PHP catch-all route doesn't exist server-side, so navigation 404s mid-test. 2. Drag/right-click flakiness (timing, not selectors): - U4 reposition/resize — `mouse.move` + `mouse.down` against the GridStack handle is order-sensitive; the headed retry mode would stabilise, but a single-shot capture run misses on every hover. - U5 style editor / U6 remove — right-click event timing on the widget wrapper varies between runs. 3. Form-validation edge case: - U2 create dashboard — the existing test instance has many newman-fork dashboards already, so the auto-derived slug collides. Either de-collide via timestamp suffix in the spec or accept the rare miss. The PR is ready for review. The remaining selector misses live in `tests/e2e/docs-screenshots.spec.ts` and can be addressed in a follow-up; the docs themselves are complete.

github-actions · 2026-05-06T08:02:21Z

Quality Report — ConductionNL/mydash @ `1c5c19a`

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 100/100
npm			✅	✅ 501/501
PHPUnit					✅
Newman					✅
Playwright					⏭️

Coverage: 90.7% (127/140 statements)

Quality workflow — 2026-05-06 08:02 UTC

Download the full PDF report from the workflow artifacts.

…ion.nl Companion to PR #132 which moved the Docusaurus deploy domain. The in-app `DOCS_URL` constant in `SidebarFooter.vue` and the `CnSettingsSection` `doc-url` in `AdminSettings.vue` still pointed at `https://mydash.app` — those are the targets of the sidebar footer's Documentation icon and the admin-page documentation link respectively, so users clicking either would have landed on the old domain. Updated both to `https://mydash.conduction.nl`. Test fixture in `SidebarFooter.spec.js` (which exact-asserts the URL) and the prose comments referencing the URL updated in lockstep so the spec still passes and the comments don't drift. No behaviour change beyond the link target. 857 vitest pass.

rubenvdlinde requested review from Rem-Dam, SudoThijn and remko48 as code owners May 6, 2026 06:42

rubenvdlinde requested review from WilcoLouwerse, bbrands02 and rjzondervan as code owners May 6, 2026 06:45

rubenvdlinde merged commit 2f2d5a0 into development May 6, 2026
49 checks passed

rubenvdlinde deleted the feature/user-and-admin-docs branch May 6, 2026 08:13

rubenvdlinde mentioned this pull request May 6, 2026

feat(in-app-docs): point in-app Documentation links at mydash.conduction.nl #133

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(tutorials): user + admin walkthroughs with durable screenshot capture#132

docs(tutorials): user + admin walkthroughs with durable screenshot capture#132
rubenvdlinde merged 7 commits intodevelopmentfrom
feature/user-and-admin-docs

rubenvdlinde commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

rubenvdlinde commented May 6, 2026

Summary

End-user track (docs/tutorials/user/)

Admin track (docs/tutorials/admin/)

Screenshot capture

Build

Test plan

Notes

Uh oh!

github-actions Bot commented May 6, 2026

Quality Report — ConductionNL/mydash @ 6f12293

Uh oh!

github-actions Bot commented May 6, 2026

Quality Report — ConductionNL/mydash @ b766354

Uh oh!

github-actions Bot commented May 6, 2026

Quality Report — ConductionNL/mydash @ 39fde97

Uh oh!

github-actions Bot commented May 6, 2026

Quality Report — ConductionNL/mydash @ 56aaea6

Uh oh!

github-actions Bot commented May 6, 2026

Quality Report — ConductionNL/mydash @ 0f6a9ad

Uh oh!

github-actions Bot commented May 6, 2026

Quality Report — ConductionNL/mydash @ 4bc4e51

Uh oh!

github-actions Bot commented May 6, 2026

Quality Report — ConductionNL/mydash @ 1c5c19a

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

End-user track (`docs/tutorials/user/`)

Admin track (`docs/tutorials/admin/`)

Quality Report — ConductionNL/mydash @ `6f12293`

Quality Report — ConductionNL/mydash @ `b766354`

Quality Report — ConductionNL/mydash @ `39fde97`

Quality Report — ConductionNL/mydash @ `56aaea6`

Quality Report — ConductionNL/mydash @ `0f6a9ad`

Quality Report — ConductionNL/mydash @ `4bc4e51`

Quality Report — ConductionNL/mydash @ `1c5c19a`