Skip to content

docs: add the browserless behavior changes to the upgrade guide - #6101

Merged
Artur- merged 4 commits into
mainfrom
docs/browserless-upgrade-notes
Sep 22, 2026
Merged

Artur- merged 4 commits into
mainfrom
docs/browserless-upgrade-notes

Conversation

@mshabarov

Copy link
Copy Markdown
Contributor

Summary

Four changes in Browserless Test 1.2, which is what Vaadin 25.3 ships, break tests that pass today. The TestBench and Browserless Testing section of the upgrade guide mentions none of them, so a suite that starts failing after the upgrade has nothing to point to.

  • vaadin/browserless-test#211NumberFieldTester, DatePickerTester, TimePickerTester and DateTimePickerTester commit a value that violates min, max, step or a required constraint, instead of throwing. Every assertThrows(IllegalArgumentException.class, ...) around those calls fails.
  • vaadin/browserless-test#139isUsable() returns false for a read-only value component, so setting a value on a read-only field through its tester now throws.
  • vaadin/browserless-test#203 — a component set as a Grid column header, footer or editor is found by a query, where the lookup used to fail.
  • vaadin/browserless-test#190CheckboxGroupTester.updateSelection is private and no longer appears on the generated locator.

What changed

Four subsections in articles/upgrading/index.adoc, under the existing TestBench and Browserless Testing heading, each saying what changed and what to write instead. The first carries a before-and-after snippet, and links to Component Testers for the full rule.

Notes for the reviewer

  • The isUsable() entry documents a change that #6034 already described on the Component Testers page. It is repeated here because it breaks existing tests silently, which is what this guide is for. Drop the subsection if the duplication is unwanted.
  • The cross-reference to component-testers#constraint-enforcement points at the section rewritten in docs: cover the browserless testers and methods added in 25.3 #6089, which explains which constraints still make a tester throw. Merging that first keeps the link meaningful, though the anchor exists either way.
  • The lookupServices() change from vaadin/browserless-test#148 is not here: that API is still unreleased, and its upgrade note travels with docs: describe per-test Vaadin configuration for browserless tests #6094.

How to test

Documentation only, with an inline snippet that is not compiled. The behavior matches the testers on vaadin/browserless-test main.

🤖 Generated with Claude Code

Four browserless changes in Vaadin 25.3 break existing tests, and the
upgrade guide covered none of them: value testers commit a value that
violates a constraint instead of throwing, a read-only component is no
longer usable, Grid header, footer and editor components are found by a
query, and CheckboxGroupTester.updateSelection is private.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mshabarov mshabarov added the target/v25.3 Automatically cherry-pick to the v25.3 branch label Sep 21, 2026
@mcollovati
mcollovati self-requested a review September 21, 2026 08:54
@mcollovati

Copy link
Copy Markdown
Contributor

Some more changes that should be mentioned in the upgrade guide:

Maybe also worth mentioning that test methods added to the TesterWrapper interface for TreeGridTester and GridContextMenuTester can break compilation, since previously a different overload with a different return type was taken.

getCellComponent now returns the component the grid rendered, test() returns
a more specific tester for TreeGrid and GridContextMenu, and a context menu
has to be opened before its items can be used.
@Artur-
Artur- merged commit cb62a41 into main Sep 22, 2026
9 of 10 checks passed
@Artur-
Artur- deleted the docs/browserless-upgrade-notes branch September 22, 2026 11:41
Artur- added a commit that referenced this pull request Sep 22, 2026
## Summary

Browserless Test 1.2 is what Vaadin 25.3 ships. It adds seven testers
and a set of tester methods that the *Component Testers* page does not
mention, and it changes what a value tester does with a value that
breaks a constraint. The page currently tells a test author the opposite
of what the code does.

Covered here:

- `vaadin/browserless-test#211` — `NumberFieldTester`,
`DatePickerTester`, `TimePickerTester` and `DateTimePickerTester` no
longer throw on `min` / `max` / `step` / required violations. They
commit the value and leave the field invalid, and `isValid()` asserts
the outcome. The page's *Constraint Enforcement* example claimed the
opposite.
- `vaadin/browserless-test#189` — `TreeGridTester` with `expand`,
`collapse`, `isExpanded` and `hasChildren`.
- `vaadin/browserless-test#197` — `SplitLayoutTester`, `CardTester` and
`AvatarGroupTester`.
- `vaadin/browserless-test#187` — `GridTester.deselect(int)` and
`deselectAll()`.
- `vaadin/browserless-test#186` — `AccordionTester.closeDetails()` and
`toggleDetails(String)`.
- `vaadin/browserless-test#191` — `NumberFieldTester.stepUp()` /
`stepDown()` and `isValid()`.
- `vaadin/browserless-test#183` — `DialogTester.pressEscape()` and
`clickOutside()`.
- `vaadin/browserless-test#168` — a uniform `clear()` plus the new
`clickClearButton()`.
- `vaadin/browserless-test#185` — `CheckboxTester.check()` / `uncheck()`
and `SwitchTester.switchOn()` / `switchOff()`.
- `vaadin/browserless-test#198` — `UploadTester` enforces `maxFiles`,
`maxFileSize` and accepted types, and adds `getLastUploadStatus()` and
`ensureUploaded()`.
- `vaadin/browserless-test#188` — tester interactions reach the
application as client-originated events.

Four testers released earlier, in 1.1.2, never reached the docs either,
so they are added with a `V25.2` badge: `DashboardTester`
(`vaadin/browserless-test#105`), `BreadcrumbsTester.getItemPaths()`
(`vaadin/browserless-test#107`), `TextTester`
(`vaadin/browserless-test#135`) and `MarkdownTester`
(`vaadin/browserless-test#132`).

## What changed

In `articles/flow/testing/browserless/component-testers.adoc`:

- *Using Component Testers* — one sentence saying that a tester drives
the component through the browser's path, so `isFromClient()` behaves as
it does in a running application.
- *Common Testers* — new rows for `TreeGrid`, `Accordion`,
`SplitLayout`, `Card`, `AvatarGroup`, `Dashboard`, `Text` and
`Markdown`, and new methods on the `TextField`, `Checkbox`,
`NumberField`, `Grid`, `Dialog`, `Upload`, `Breadcrumbs` and `Switch`
rows.
- *Constraint Enforcement* — rewritten around the distinction the code
makes. A constraint that keeps the value out of the field, such as
`maxLength` or an allowed character pattern, still makes the tester
throw. A constraint that only marks the field invalid is committed, as a
browser commits it, and asserted with `isValid()`.
- *Clearing a Value* — a new section for `clear()` versus
`clickClearButton()`, and the wording selection testers use instead.

## Notes for the reviewer

- `vaadin/browserless-test#185` and `#198` are merged but landed after
the `1.2.0-rc1` tag, so they are not in rc1. They need 1.2.0 final to
ship with 25.3. If the release does not pick them up, drop the `check()`
/ `uncheck()`, `switchOn()` / `switchOff()`, `getLastUploadStatus()` and
`ensureUploaded()` entries.
- The behavior change from `vaadin/browserless-test#211` is breaking for
existing tests that assert `assertThrows(IllegalArgumentException.class,
...)`. The upgrade-guide note is #6101.
- `Dashboard` is a commercial component, like the `GridPro` and `Chart`
rows already in the table.

## How to test

Documentation only, with inline snippets that are not compiled. The
behavior matches `NumberFieldTester`, `TreeGridTester`,
`AccordionTester`, `DialogTester`, `UploadTester` and the other testers
on `vaadin/browserless-test` `main`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: totally-not-ai[bot] <290682512+totally-not-ai[bot]@users.noreply.github.com>
Co-authored-by: Artur Signell <artur@vaadin.com>
Artur- pushed a commit that referenced this pull request Sep 22, 2026
… (CP: v25.3) (#6133)

Co-authored-by: Mikhail Shabarov <61410877+mshabarov@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: totally-not-ai[bot] <290682512+totally-not-ai[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cherry-picked-v25.3 target/v25.3 Automatically cherry-pick to the v25.3 branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants