Skip to main content

​
Overview

@PlaywrightElement is a runtime annotation used to associate a Drama Finder element class with its corresponding Vaadin component HTML tag name. This annotation is applied to element wrapper classes that extend VaadinElement.

​
Annotation Details

​
@Target
ElementType.TYPE
This annotation can only be applied to class declarations
​
@Retention
RetentionPolicy.RUNTIME
The annotation is retained at runtime and accessible via reflection
​
@Inherited
boolean
The annotation is inherited by subclasses

​
Annotation Parameter

​
value()

Specifies the HTML tag name for the Vaadin component.
​
value
String
required
The HTML tag name of the Vaadin component (e.g., vaadin-button, vaadin-text-field)
​
return
String
The tag name for the element

​
Usage Examples

​
Basic Usage

@PlaywrightElement(ButtonElement.FIELD_TAG_NAME)
public class ButtonElement extends VaadinElement
        implements FocusableElement, HasAriaLabelElement, HasEnabledElement {
    
    public static final String FIELD_TAG_NAME = "vaadin-button";
    
    public ButtonElement(Locator locator) {
        super(locator);
    }
    
    // Component-specific methods...
}

​
With Static Tag Name Constant

@PlaywrightElement(TextFieldElement.FIELD_TAG_NAME)
public class TextFieldElement extends VaadinElement {
    
    public static final String FIELD_TAG_NAME = "vaadin-text-field";
    
    public TextFieldElement(Locator locator) {
        super(locator);
    }
    
    public static TextFieldElement getByLabel(Page page, String label) {
        return new TextFieldElement(
            page.locator(FIELD_TAG_NAME)
                .filter(new Locator.FilterOptions()
                    .setHas(page.getByRole(AriaRole.TEXTBOX,
                        new Page.GetByRoleOptions().setName(label))))
                .first());
    }
}

​
Inherited Annotation

Since @PlaywrightElement is marked with @Inherited, subclasses automatically inherit the annotation: 
@PlaywrightElement(TextFieldElement.FIELD_TAG_NAME)
public class TextFieldElement extends VaadinElement {
    public static final String FIELD_TAG_NAME = "vaadin-text-field";
    // ...
}

// EmailFieldElement inherits the @PlaywrightElement annotation
public class EmailFieldElement extends TextFieldElement {
    public static final String FIELD_TAG_NAME = "vaadin-email-field";
    
    public EmailFieldElement(Locator locator) {
        super(locator);
    }
}

​
Common Tag Names

Here are some commonly used Vaadin component tag names:
ComponentTag Name
Buttonvaadin-button
Text Fieldvaadin-text-field
Password Fieldvaadin-password-field
Email Fieldvaadin-email-field
Number Fieldvaadin-number-field
Text Areavaadin-text-area
Checkboxvaadin-checkbox
Radio Buttonvaadin-radio-button
Selectvaadin-select
Combo Boxvaadin-combo-box
Date Pickervaadin-date-picker
Time Pickervaadin-time-picker
Gridvaadin-grid
Dialogvaadin-dialog

​
Purpose and Benefits

​
Runtime Introspection

The annotation enables runtime introspection of element classes to determine their associated Vaadin component tag: 
PlaywrightElement annotation = ButtonElement.class.getAnnotation(PlaywrightElement.class);
String tagName = annotation.value();
// tagName = "vaadin-button"

​
Framework Integration

The annotation can be used by testing frameworks or tooling to:
  • Automatically generate locators based on tag names
  • Validate that element classes match their corresponding Vaadin components
  • Generate documentation or test reports
  • Provide IDE autocomplete suggestions

​
Convention and Documentation

By requiring the annotation on all element classes, Drama Finder ensures:
  • Consistent naming conventions across element wrappers
  • Clear documentation of which Vaadin component each class wraps
  • Easy identification of supported components

​
Notes

  • Always define the tag name as a public static final constant (e.g., FIELD_TAG_NAME) and reference it in the annotation.
  • The annotation value should match the exact HTML tag name used by the Vaadin component.
  • The @Inherited property means child classes inherit the annotation, but you may want to override it if the child represents a different tag.
  • This annotation is required for all classes that extend VaadinElement in the Drama Finder library.

Build docs developers (and LLMs) love

Get started for freeTalk to us