Documentation Index
Fetch the complete documentation index at: https://mintlify.com/parttio/dramafinder/llms.txt
Use this file to discover all available pages before exploring further.
Overview
HasHelperElement provides methods for interacting with helper text in Vaadin components. Helper text appears below form fields to provide additional guidance, explanations, or examples to users. It is persistent (unlike tooltips) and complements field labels.
Interface Location: org.vaadin.addons.dramafinder.element.shared.HasHelperElement
Methods
getHelperLocator()
default Locator getHelperLocator()
slot="helper".
Returns: Locator - Locator for the first element with slot="helper"
getHelperText()
default String getHelperText()
String - The helper text
assertHelperHasText()
default void assertHelperHasText(String helperText)
AssertionError if the helper text does not match
Implementing Classes
The following element classes implement HasHelperElement:
- All text input components (via
HasInputFieldElement)
RadioButtonGroupElement- All components that support the helper slot
Usage Example
import org.vaadin.addons.dramafinder.element.TextFieldElement;
import org.vaadin.addons.dramafinder.element.PasswordFieldElement;
import com.microsoft.playwright.Page;
public class HelperTest {
void testHelperText(Page page) {
TextFieldElement username = TextFieldElement.getByLabel(page, "Username");
PasswordFieldElement password = PasswordFieldElement.getByLabel(page, "Password");
// Assert helper text provides guidance
username.assertHelperHasText("Choose a unique username between 3-20 characters");
password.assertHelperHasText("Must be at least 8 characters with 1 number and 1 special character");
// Get helper text programmatically
String helpText = username.getHelperText();
System.out.println("Username help: " + helpText);
// Get locator for custom assertions
Locator helperLocator = password.getHelperLocator();
assertThat(helperLocator).isVisible();
}
}
Implementation Details
Slot-Based Architecture
Vaadin components use slots for extensible content areas. Helper text is placed in the helper slot:
getLocator().locator("*[slot=\"helper\"]").first()
slot="helper" attribute.
Helper Text Placement
Helper text typically appears:
- Below the input field
- Above any error messages
- In a smaller, muted font
- Persistently visible (not on hover/focus like tooltips)
Difference from Error Messages
Helper text is distinct from error messages:
- Helper text: Proactive guidance (always visible when set)
- Error messages: Reactive feedback (shown when invalid)
Both use slots but different ones (helper vs error-message).
Testing Patterns
Test Guidance Text
TextFieldElement email = TextFieldElement.getByLabel(page, "Email");
email.assertHelperHasText("We'll never share your email with anyone");
TextFieldElement phone = TextFieldElement.getByLabel(page, "Phone");
phone.assertHelperHasText("Include country code for international numbers");
TextFieldElement date = TextFieldElement.getByLabel(page, "Birth Date");
date.assertHelperHasText("Format: MM/DD/YYYY");
TextFieldElement ssn = TextFieldElement.getByLabel(page, "SSN");
ssn.assertHelperHasText("Format: XXX-XX-XXXX");
Test Character Count
TextAreaElement bio = TextAreaElement.getByLabel(page, "Bio");
// Initial helper
bio.assertHelperHasText("0 / 500 characters");
// After typing
bio.setValue("Hello world");
bio.assertHelperHasText("11 / 500 characters");
Test Field Requirements
PasswordFieldElement password = PasswordFieldElement.getByLabel(page, "New Password");
password.assertHelperHasText("Must contain: 8+ characters, 1 uppercase, 1 number, 1 special character");
Test Dynamic Helper Changes
TextFieldElement field = TextFieldElement.getByLabel(page, "Amount");
// Initial helper
field.assertHelperHasText("Enter amount in USD");
// Change currency
SelectElement currency = SelectElement.getByLabel(page, "Currency");
currency.selectByText("EUR");
// Helper updates
field.assertHelperHasText("Enter amount in EUR");
Best Practices
Use Helper Text for Additional Context
Helper text should provide useful information without repeating the label:
// Good: Adds useful context
field.assertLabel("Password");
field.assertHelperHasText("At least 8 characters");
// Bad: Repeats label
// field.assertLabel("Password");
// field.assertHelperHasText("Enter your password");
Keep Helper Text Concise
Helper text should be brief and scannable:
// Good: Brief and clear
field.assertHelperHasText("3-20 characters, letters and numbers only");
// Too verbose:
// field.assertHelperHasText("Please enter a username that is between 3 and 20 characters long and contains only letters and numbers without any special characters or spaces");
Use for Proactive Guidance
Helper text is for guidance before errors occur:
// Helper: Proactive
field.assertHelperHasText("Must include @ symbol");
// Error: Reactive (shown after validation fails)
field.assertErrorMessage("Please enter a valid email address");
Test Helper Text Visibility
Verify helper text is visible when expected:
TextFieldElement field = TextFieldElement.getByLabel(page, "API Key");
// Helper should be visible
Locator helper = field.getHelperLocator();
assertThat(helper).isVisible();
assertThat(helper).hasText("Found in your account settings");
Common Use Cases
Password Requirements
PasswordFieldElement password = PasswordFieldElement.getByLabel(page, "Password");
password.assertHelperHasText("Minimum 8 characters with at least 1 number");
Optional Field Indication
TextFieldElement middle = TextFieldElement.getByLabel(page, "Middle Name");
middle.assertHelperHasText("Optional");
TextFieldElement phone = TextFieldElement.getByLabel(page, "Phone");
phone.assertHelperHasText("Format: (555) 555-5555");
Privacy Assurances
TextFieldElement email = TextFieldElement.getByLabel(page, "Email");
email.assertHelperHasText("We will never share your email address");
Character Limits
TextAreaElement comment = TextAreaElement.getByLabel(page, "Comment");
comment.assertHelperHasText("Maximum 500 characters");
Dynamic Feedback
TextFieldElement username = TextFieldElement.getByLabel(page, "Username");
// Before typing
username.assertHelperHasText("Choose a unique username");
// After typing
username.setValue("john123");
username.blur();
// May show availability
username.assertHelperHasText("Username is available");
Accessibility Considerations
Helper Text and Screen Readers
Helper text should be associated with the field for screen readers. Vaadin handles this automatically through the helper slot mechanism.
Don’t Use for Critical Errors
Critical validation errors should use error messages, not helper text:
// Correct: Use error message for validation failures
field.setValue("invalid");
field.blur();
field.assertInvalid();
field.assertErrorMessage("This field is required");
// Don't rely solely on helper text for validation feedback
Supplement, Don’t Replace Labels
Helper text supplements labels but doesn’t replace them:
// Both label and helper provide value
field.assertLabel("Email Address");
field.assertHelperHasText("We'll send a confirmation to this address");