Skip to content

Add forms mode-selection and TestBench reliability guidance#5780

Merged
peholmst merged 1 commit into
mainfrom
docs-forms-testing-guidance
Jul 3, 2026
Merged

Add forms mode-selection and TestBench reliability guidance#5780
peholmst merged 1 commit into
mainfrom
docs-forms-testing-guidance

Conversation

@peholmst

@peholmst peholmst commented Jul 3, 2026

Copy link
Copy Markdown
Member

What

Adds best-practice guidance to three existing pages:

  • building-apps/forms-data/add-form/fields-and-binding.adoc — a "Choosing a Mode" scenario table mapping common form situations (Save/Cancel buttons, multi-step wizard, inline Grid editing, settings panel, filter bar) to buffered vs. write-through Binder mode.
  • flow/binding-data/components-binder-beans.adoc — a TIP recommending explicit forField().bind() with method references over bindInstanceFields() for non-trivial forms, and noting that binding by string property name is best reserved for record FDOs.
  • flow/testing/end-to-end/reliable-tests.adoc — two new sections: "Keeping Tests Focused and Independent" (reserve end-to-end tests for critical journeys, push coverage down to browserless tests, keep tests independent) and "Waiting for Asynchronous Updates" (wait via waitForFirst()/waitUntil() rather than Thread.sleep()).

Why

This guidance previously lived only in the Vaadin agent skills (forms-and-validation, testbench-testing). Those skills were otherwise restatements of existing docs, so they're being retired; this content — decision tables and best-practice recommendations that a human reader wants too — belongs in the documentation. The docs already covered the underlying mechanics (Binder modes, validators/converters, page objects, the browserless-vs-e2e comparison); these additions fill the gaps in decision and do/don't guidance.

Reviewer notes

  • Additive only (46 lines across 3 files); no existing content changed.
  • Follows repo conventions: [methodname]/[classname]/[guibutton] macros, cols-based tables, and {articles} xref syntax (verified against existing usage in the repo).
  • Coupled change: the agent-skills PR that retires the two skills is Prune skills that only restate the documentation agent-skills#9 — these should land together, since the vaadin-form-layout skill now points readers at these doc guides.
  • An unrelated package-lock.json regeneration in the working tree was intentionally left out of this content PR.

🤖 Generated with Claude Code

Consolidate best-practice guidance that was previously only available in
the agent skills into the documentation:

- fields-and-binding: add a "Choosing a Mode" scenario table mapping common
  form situations (Save/Cancel, wizard, inline grid edit, settings, filter
  bar) to buffered vs write-through Binder mode.
- components-binder-beans: recommend explicit forField().bind() over
  bindInstanceFields for non-trivial forms, and note string property names
  are best reserved for record FDOs.
- reliable-tests: add "Keeping Tests Focused and Independent" (reserve e2e
  for critical journeys, push coverage down to browserless, keep tests
  independent) and "Waiting for Asynchronous Updates" (wait via
  waitForFirst()/waitUntil() rather than Thread.sleep()).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@peholmst peholmst added the target/v25.2 Automatically cherry-pick to the v25.2 branch label Jul 3, 2026
@peholmst peholmst merged commit 4481899 into main Jul 3, 2026
7 of 8 checks passed
@peholmst peholmst deleted the docs-forms-testing-guidance branch July 3, 2026 08:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants