docs: document the 25.3 browserless tester, client engine and navigation changes - #6120
Conversation
The "Constraint Enforcement" section stated the opposite of the shipped behavior: value testers commit a value that only breaks a validation constraint and leave the field invalid, and text testers refuse only input the browser physically prevents. The Grid Context Menu example used ContextMenuTester, which test(gridContextMenu) no longer returns, and the context menu section claimed that a menu need not be opened first, while clickItem() and friends now throw on a closed menu. Rewrite those sections, add the 25.3 tester additions to the Common Testers table (TreeGrid, GridContextMenu, SplitLayout, Card, AvatarGroup, Accordion, Grid deselection, getCellComponent/renderCellComponent, dialog dismissal, step buttons, clear()/clickClearButton(), getItemTexts(), upload constraints, slot-scoped finders) and document the behavior changes in the migration guide.
Add the withinSlot() filter to the component query and locator filter tables, and a section on what find() reaches: components a grid renders per item are reached through getCellComponent()/renderCellComponent(), overlay content only while the overlay is open, and column header, footer and editor components by a plain find().
`@BrowserlessTestConfig`, the extension builder methods and the application context builder methods for application properties, feature flags and lookup services were documented only in the module README.
Three 25.3 changes had no upgrade note: - The client-side engine is TypeScript bundled by Vite; the GWT engine and the com.vaadin.client.* API are gone from flow-client. The pages that described the engine as a widget set are updated as well. - npm version pinning is read from META-INF/VAADIN/versions/ in every jar, and the constants naming the old classpath-root files are removed. The versions-file format is documented for add-on authors. - With a login view configured, an unauthorized sub-resource request is answered with 401 instead of a redirect to the login view.
Document the warning Flow logs when JavaScript invocations pile up for a UI whose client is not receiving responses, and the UI.getLastUpdateSentTimestamp() pattern a background job can use to stop scheduling updates while that is the case.
UI.navigate(String) parses the query string and fragment of the location, and combining such a location with a separate QueryParameters object is rejected.
A client property write the bound signal cannot hold is logged and reverted, and a shared signal write with an erased value type throws InvalidSignalValueTypeException.
- The fragment of a navigation location isn't a query parameter; only the query string is parsed into QueryParameters. - Label the deep cross-references with the section they point at, rather than with the title of the migration page. - The migration page lead and front matter now say that it also covers tester behavior changes, and the upgrade guide points to that section. - Restore the reason why `unsafe-eval` is needed: the client evaluates the expressions the server sends by constructing functions from them. - Use the repository's "sub-menu" spelling.
The browserless testers and methods, the constraint enforcement rewrite, the per-test configuration, the query visibility rules and the navigation query string are already handled by the open PRs for those topics. What remains here is what none of them covers: the overlay component docs, slot-scoped finders and the withinSlot filter, the upload constraint model, and the tester rows for GridContextMenu, LoginOverlay and the date and time pickers.
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-6120.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Built from 41c2834 |
The upload gate is a special case of constraint enforcement, so it reads after it rather than before it. The date and time picker rows move to the pull request that documents the methods they list.
|
|
||
| | [since:com.vaadin:vaadin@V25.3]#[classname]`GridContextMenu`# | ||
| | [classname]`GridContextMenuTester`: [methodname]`open(row)`, [methodname]`clickItem(String, String...)`, [methodname]`getItemTexts()`. See <<overlay-components#grid-context-menu, Grid Context Menu>> | ||
|
|
||
| | [classname]`LoginOverlay` | ||
| | [methodname]`openOverlay()`, [methodname]`isOpen()`, [since:com.vaadin:vaadin@V25.3]#[methodname]`findInFooter(Class)`, [methodname]`findInCustomFormArea(Class)`# | ||
|
|
There was a problem hiding this comment.
Agreed, moved — both rows are now in #6089 (vaadin/docs@docs/browserless-1.2-tester-api), next to the rest of the tester table additions. The GridContextMenu row there is worded to stand on its own ("obtained with test(grid).contextMenu(row)") instead of linking to the Grid Context Menu section this PR adds, so it doesn't depend on the merge order.
This page now keeps only what isn't covered elsewhere: the slot-scoped finders and the upload constraint model.
The GridContextMenu and LoginOverlay rows belong with the rest of the 1.2 tester additions, so this page keeps only the slot-scoped finders and the upload constraint model.
|
|
||
|
|
||
| [role="since:com.vaadin:vaadin@V25.3"] | ||
| == Pinning npm Package Versions |
There was a problem hiding this comment.
This is also documented in #6091. Integrate this content in that PR
There was a problem hiding this comment.
Agreed, integrated — the section is gone from here, and the two things it had that #6091 didn't are now in that PR: the exclusions array for naming the packages a pinned one replaces, and the rule that a version declared by a scanned @NpmPackage or by the application's own package.json wins over a pinned one.
What stays here is the upgrade-guide entry, since #6091 documents the feature rather than the move: versions files are read from META-INF/VAADIN/versions/ instead of the vaadin-core-versions.json and vaadin-versions.json files at the classpath root, and Constants.VAADIN_CORE_VERSIONS_JSON and Constants.VAADIN_VERSIONS_JSON are removed. It no longer links to Package a Component, so it stands on its own whichever PR lands first — worth adding a link to the new section once #6091 is in.
|
|
||
|
|
||
| [role="since:com.vaadin:vaadin@V25.3"] | ||
| == Updates the Client Doesn't Receive |
There was a problem hiding this comment.
Agreed, moved — the section is gone from this page, and the parts of it that #6099 didn't have are now in that PR's "Undelivered Invocations" section: the guard a background task uses, written as code, the caveat that the timestamp says when updates were written towards the browser rather than received, and the debug logger that names the call site of the invocation which triggered the warning.
#6099 also now carries a short pointer from "Avoiding Floods" on this page to that section, so flooding and never-delivered updates link to each other. Keeping the link inside that PR means it ships together with the anchor it points at.
Nothing about undelivered invocations is left in this PR.
The npm version pinning section is covered by the change that documents the feature, so the upgrade note here points at that page instead of repeating the file format.
The npm versions-file format is documented with the add-on packaging feature, so the upgrade note states the move and leaves it at that.
The retention, the warning and the alternatives are documented with the executeJs() reference material, so this page doesn't repeat them.
4 participants
Summary
Documents several Vaadin 25.3 changes that had no docs yet: new browserless tester features and behavior changes, the TypeScript client-side engine, navigating to a location that carries a query string, and two security and signal changes. Docs only — no product code is touched.
What changed
This is a documentation-only change. Nothing in the product behaves differently because of it.
Browserless testing
clickItem(),isItemChecked(),getItemTexts()andgetItemTooltipText()throw on a closed menu. The old text said the opposite.find()is the one method that still works on a closed menu.GridContextMenu:test(gridContextMenu)now returns aGridContextMenuTester, not aContextMenuTester. Documented withopen(row)andtest(grid).contextMenu(row), plus a note for code that used an explicit variable type.getItemTexts()for context menus and menu bars, slot-scoped finders (findInHeader(),findInFooter(),findInPrimary(),findInSecondary(),findInCustomFormArea()), thewithinSlot()query and locator filter, and the upload constraint model (maxFiles, max file size and accepted types,getLastUploadStatus(),ensureUploaded(),removeFile()).Navigation
UI.navigate(String)parses a query string and fragment in the location itself. Passing a separateQueryParametersobject alongside such a location throws anIllegalArgumentException.Signals
InvalidSignalValueTypeException.Upgrade notes for 25.3
com.vaadin.client.*API are gone fromflow-client. Pages that called the engine a "widget set" are updated, and the CSP page now explains whyunsafe-evalis still needed.META-INF/VAADIN/versions/in every JAR; the constants naming the old classpath-root files are removed.401instead of a redirect to the login view.