From 59e6db3d0f5a47691dc93b9a34a91239e8e9d322 Mon Sep 17 00:00:00 2001
From: "totally-not-ai[bot]"
 <290682512+totally-not-ai[bot]@users.noreply.github.com>
Date: Sat, 19 Sep 2026 08:28:02 +0200
Subject: [PATCH] feat!: refuse text values the browser physically prevents in
 TextFieldTester and TextAreaTester (#252)

`TextFieldTester.setValue` and `TextAreaTester.setValue` used to accept
values a real user could never type, such as text longer than
`maxLength` or characters that `allowedCharPattern` blocks. They now
refuse those values with an `IllegalArgumentException`, so a test cannot
reach a state the browser would never produce.

Fixes #248
---
 CONVENTIONS.md                                |   8 +-
 guidelines/testers.md                         |  13 +-
 .../textfield/TextAreaTesterTest.java         |  39 ++++-
 .../textfield/TextFieldTesterTest.java        |  41 ++++-
 .../component/textfield/TextAreaTester.java   |  27 +++-
 .../component/textfield/TextFieldTester.java  |  29 +++-
 .../textfield/TextInputConstraints.java       | 143 ++++++++++++++++++
 7 files changed, 271 insertions(+), 29 deletions(-)
 create mode 100644 shared/src/main/java/com/vaadin/flow/component/textfield/TextInputConstraints.java

diff --git a/CONVENTIONS.md b/CONVENTIONS.md
index 2eadf3ff..58769be8 100644
--- a/CONVENTIONS.md
+++ b/CONVENTIONS.md
@@ -52,8 +52,12 @@ with `isValid()` rather than refusing the value at set time.
 
 Refuse a value only when the real control physically cannot produce it: a
 slider clamps to its range and snaps to its step, so `RangeInputTester` and
-`NumberSliderTester` do reject out-of-range and off-step values. Structural
-refusals stay too, such as `null` on a field whose empty value is not `null`.
+`NumberSliderTester` do reject out-of-range and off-step values, and a text
+input truncates at `maxLength` and filters the keystrokes `allowedCharPattern`
+does not match, so `TextFieldTester` and `TextAreaTester` reject a value that
+breaks either one. `minLength`, `pattern` and required are validation-only and
+keep committing an invalid value. Structural refusals stay too, such as `null`
+on a field whose empty value is not `null`.
 
 Read-only state counts towards usability. `isUsable()` is enabled + attached +
 effectively visible + not inert + not read-only, and effective visibility walks
diff --git a/guidelines/testers.md b/guidelines/testers.md
index f5865e1c..7e0faf9d 100644
--- a/guidelines/testers.md
+++ b/guidelines/testers.md
@@ -81,9 +81,20 @@ for it — not enforced at set time.
 
 The exception is a control that physically cannot produce the value: a slider
 clamps to its range and snaps to its step, so `RangeInputTester` and
-`NumberSliderTester` do refuse out-of-range and off-step values. Structural
+`NumberSliderTester` do refuse out-of-range and off-step values. A text input
+truncates what is over `maxLength` and filters out the keystrokes
+`allowedCharPattern` does not match, so `TextFieldTester` and `TextAreaTester`
+refuse a value that breaks either one — while `minLength`, `pattern` and
+required stay validation-only and keep committing an invalid value. Structural
 refusals stay too, such as `null` on a field whose empty value is not `null`.
 
+Where the line falls is a question about the control, not about the constraint:
+ask whether a user sitting in front of the component could hand the field that
+value at all. When they could not, refuse it with an `IllegalArgumentException`
+whose message says what the browser does instead, rather than silently
+correcting the value — a test that asks for the impossible has a bug in it, and
+truncating or clamping behind its back would hide it.
+
 `isValid()` means "not marked invalid, and the current value passes the
 component's own default validator" — it delegates to `getDefaultValidator()`
 rather than re-checking required / `min` / `max` / `step` by hand. Re-checking
diff --git a/junit6/src/test/java/com/vaadin/flow/component/textfield/TextAreaTesterTest.java b/junit6/src/test/java/com/vaadin/flow/component/textfield/TextAreaTesterTest.java
index 43f007b2..3960ecf3 100644
--- a/junit6/src/test/java/com/vaadin/flow/component/textfield/TextAreaTesterTest.java
+++ b/junit6/src/test/java/com/vaadin/flow/component/textfield/TextAreaTesterTest.java
@@ -93,26 +93,33 @@ public void nonInteractableField_throwsOnSetValue() {
     @Test
     void textAreaWithValidation_doNotPreventInvalid_doNotThrow() {
         // Only accept numbers
-        view.textArea.setAllowedCharPattern("\\d*");
+        view.textArea.setPattern("\\d*");
 
         final TextAreaTester<TextArea> ta_ = test(view.textArea);
         final String faultyValue = "Invalid value, but doesn't throw";
         ta_.setValue(faultyValue);
         Assertions.assertEquals(faultyValue, view.textArea.getValue(),
                 "Value should have been set.");
+        Assertions.assertTrue(ta_.getComponent().isInvalid(),
+                "A validation-only constraint leaves the field invalid");
     }
 
     @Test
-    public void textAreaWithPattern_patternIsValidated() {
+    public void textAreaWithAllowedCharPattern_disallowedCharIsRefused() {
         TextArea tf = view.textArea;
         // Only accept numbers
-        tf.setPattern("\\d*");
+        tf.setAllowedCharPattern("\\d");
 
         final TextAreaTester<TextArea> ta_ = test(tf);
         ta_.setValue("1234");
-
         Assertions.assertEquals("1234", tf.getValue());
-        Assertions.assertFalse(ta_.getComponent().isInvalid());
+
+        Assertions.assertThrows(IllegalArgumentException.class,
+                () -> ta_.setValue("hello"),
+                "The browser filters out a keystroke the allowed char pattern "
+                        + "does not match");
+        Assertions.assertEquals("1234", tf.getValue(),
+                "A refused value should not have been committed");
     }
 
     @Test
@@ -126,13 +133,29 @@ public void textAreaWithMinLength_lengthIsChecked() {
     }
 
     @Test
-    public void textAreaWithMaxLength_lengthIsChecked() {
+    public void textAreaWithMaxLength_longerValueIsRefused() {
         TextArea tf = view.textArea;
         tf.setMaxLength(3);
 
         final TextAreaTester<TextArea> ta_ = test(tf);
-        ta_.setValue("1234");
-        Assertions.assertTrue(ta_.getComponent().isInvalid());
+        ta_.setValue("123");
+        Assertions.assertEquals("123", tf.getValue(),
+                "A value at the limit should have been set");
+
+        Assertions.assertThrows(IllegalArgumentException.class,
+                () -> ta_.setValue("1234"),
+                "The browser truncates the characters over maxLength");
+        Assertions.assertEquals("123", tf.getValue(),
+                "A refused value should not have been committed");
+    }
+
+    @Test
+    public void textArea_nullValue_isRefused() {
+        final TextAreaTester<TextArea> ta_ = test(view.textArea);
+
+        Assertions.assertThrows(IllegalArgumentException.class,
+                () -> ta_.setValue(null),
+                "A text area has no null state, clear() empties it");
     }
 
     @Test
diff --git a/junit6/src/test/java/com/vaadin/flow/component/textfield/TextFieldTesterTest.java b/junit6/src/test/java/com/vaadin/flow/component/textfield/TextFieldTesterTest.java
index 96aef722..92523371 100644
--- a/junit6/src/test/java/com/vaadin/flow/component/textfield/TextFieldTesterTest.java
+++ b/junit6/src/test/java/com/vaadin/flow/component/textfield/TextFieldTesterTest.java
@@ -102,20 +102,32 @@ void textFieldWithValidation_doNotPreventInvalid_doNotThrow() {
         tf_.setValue(faultyValue);
         Assertions.assertEquals(faultyValue, view.textField.getValue(),
                 "Value should have been set.");
+        Assertions.assertTrue(tf_.getComponent().isInvalid(),
+                "A validation-only constraint leaves the field invalid");
     }
 
     @Test
-    public void textFieldWithPattern_patternIsValidated() {
+    public void textFieldWithAllowedCharPattern_disallowedCharIsRefused() {
         TextField tf = view.textField;
         // Only accept numbers
-        tf.setAllowedCharPattern("\\d*");
+        tf.setAllowedCharPattern("\\d");
 
         final TextFieldTester<TextField, String> tf_ = test(tf);
         tf_.setValue("1234");
-
         Assertions.assertEquals("1234", tf.getValue());
+
+        Assertions.assertThrows(IllegalArgumentException.class,
+                () -> tf_.setValue("hello"),
+                "The browser filters out a keystroke the allowed char pattern "
+                        + "does not match");
+        Assertions.assertEquals("1234", tf.getValue(),
+                "A refused value should not have been committed");
+
+        // The browser only warns about a pattern it cannot compile.
+        tf.setAllowedCharPattern("[0-9");
         tf_.setValue("hello");
-        Assertions.assertFalse(tf_.getComponent().isInvalid());
+        Assertions.assertEquals("hello", tf.getValue(),
+                "A pattern that is not a regular expression restricts nothing");
     }
 
     @Test
@@ -129,13 +141,28 @@ public void textFieldWithMinLength_lengthIsChecked() {
     }
 
     @Test
-    public void textFieldWithMaxLength_lengthIsChecked() {
+    public void textFieldWithMaxLength_longerValueIsRefused() {
         TextField tf = view.textField;
         tf.setMaxLength(3);
 
         final TextFieldTester<TextField, String> tf_ = test(tf);
-        tf_.setValue("1234");
-        Assertions.assertTrue(tf_.getComponent().isInvalid());
+        tf_.setValue("123");
+        Assertions.assertEquals("123", tf.getValue(),
+                "A value at the limit should have been set");
+
+        Assertions.assertThrows(IllegalArgumentException.class,
+                () -> tf_.setValue("1234"),
+                "The browser truncates the characters over maxLength");
+        Assertions.assertEquals("123", tf.getValue(),
+                "A refused value should not have been committed");
+
+        tf.setMaxLength(0);
+        Assertions.assertThrows(IllegalArgumentException.class,
+                () -> tf_.setValue("1"),
+                "A maxLength of zero is a limit of zero, not an unset limit");
+        tf_.setValue("");
+        Assertions.assertEquals("", tf.getValue(),
+                "Emptying the field stays possible under any limit");
     }
 
     @Test
diff --git a/shared/src/main/java/com/vaadin/flow/component/textfield/TextAreaTester.java b/shared/src/main/java/com/vaadin/flow/component/textfield/TextAreaTester.java
index 8063425c..993ca7aa 100644
--- a/shared/src/main/java/com/vaadin/flow/component/textfield/TextAreaTester.java
+++ b/shared/src/main/java/com/vaadin/flow/component/textfield/TextAreaTester.java
@@ -38,16 +38,35 @@ public TextAreaTester(T component) {
     }
 
     /**
-     * Set the value to the component if it is usable.
-     *
-     * For a non interactable component an IllegalStateException will be thrown
-     * as the end user would not be able to set a value.
+     * Set the given value for the component, as the user would type it.
+     * <p/>
+     * A value that only breaks a validation constraint — shorter than
+     * {@literal minLength}, not matching {@literal pattern}, or the empty value
+     * on a required field — is committed all the same, because the browser
+     * commits it too and simply leaves the field invalid. Assert that outcome
+     * with {@link com.vaadin.flow.component.HasValidation#isInvalid()} instead
+     * of expecting this method to throw.
+     * <p/>
+     * A value the user physically cannot type is refused: the browser truncates
+     * what is over {@literal maxLength} and filters out the keystrokes
+     * {@literal allowedCharPattern} does not match, so a longer value or a
+     * disallowed character fails with an {@link IllegalArgumentException}. So
+     * does {@code null}, as a text area has no null state — emptying the field
+     * is {@link #clear()}.
      *
      * @param value
      *            value to set
+     * @throws IllegalStateException
+     *             if the component is not usable
+     * @throws IllegalArgumentException
+     *             if the value is one the user could not have typed
      */
     public void setValue(String value) {
         ensureComponentIsUsable();
+
+        TextInputConstraints.ensureValueIsNotNull(getComponent(), value);
+        TextInputConstraints.ensureValueCanBeTyped(getComponent(), value);
+
         setValueAsUser(value);
     }
 
diff --git a/shared/src/main/java/com/vaadin/flow/component/textfield/TextFieldTester.java b/shared/src/main/java/com/vaadin/flow/component/textfield/TextFieldTester.java
index 329e578b..863da760 100644
--- a/shared/src/main/java/com/vaadin/flow/component/textfield/TextFieldTester.java
+++ b/shared/src/main/java/com/vaadin/flow/component/textfield/TextFieldTester.java
@@ -43,20 +43,35 @@ public TextFieldTester(T component) {
     }
 
     /**
-     * Set the value to the component if it is usable.
-     *
-     * For a non interactable component an IllegalStateException will be thrown
-     * as the end user would not be able to set a value.
+     * Set the given value for the component, as the user would type it.
+     * <p/>
+     * A value that only breaks a validation constraint — shorter than
+     * {@literal minLength}, not matching {@literal pattern}, or the empty value
+     * on a required field — is committed all the same, because the browser
+     * commits it too and simply leaves the field invalid. Assert that outcome
+     * with {@link com.vaadin.flow.component.HasValidation#isInvalid()} instead
+     * of expecting this method to throw.
+     * <p/>
+     * A value the user physically cannot type is refused: the browser truncates
+     * what is over {@literal maxLength} and filters out the keystrokes
+     * {@literal allowedCharPattern} does not match, so a longer value or a
+     * disallowed character fails with an {@link IllegalArgumentException}. So
+     * does {@code null} on a field whose empty value is not {@code null}, as a
+     * text input has no null state — emptying the field is {@link #clear()}.
      *
      * @param value
      *            value to set
+     * @throws IllegalStateException
+     *             if the component is not usable
+     * @throws IllegalArgumentException
+     *             if the value is one the user could not have typed
      */
     public void setValue(V value) {
         ensureComponentIsUsable();
 
-        if (value == null && getComponent().getEmptyValue() != null) {
-            throw new IllegalArgumentException(
-                    "Field doesn't allow null values");
+        TextInputConstraints.ensureValueIsNotNull(getComponent(), value);
+        if (value instanceof String text) {
+            TextInputConstraints.ensureValueCanBeTyped(getComponent(), text);
         }
 
         setValueAsUser(value);
diff --git a/shared/src/main/java/com/vaadin/flow/component/textfield/TextInputConstraints.java b/shared/src/main/java/com/vaadin/flow/component/textfield/TextInputConstraints.java
new file mode 100644
index 00000000..05ef5e1a
--- /dev/null
+++ b/shared/src/main/java/com/vaadin/flow/component/textfield/TextInputConstraints.java
@@ -0,0 +1,143 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.component.textfield;
+
+import java.util.OptionalInt;
+import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
+
+import com.vaadin.flow.component.Component;
+import com.vaadin.flow.component.HasValue;
+import com.vaadin.flow.component.shared.HasAllowedCharPattern;
+
+/**
+ * The values a text input cannot be made to hold, shared by the testers of the
+ * text based fields.
+ * <p>
+ * Only the two constraints the browser physically enforces belong here:
+ * {@literal maxlength} truncates the extra characters and
+ * {@literal allowedCharPattern} filters the keystrokes it does not match, so
+ * neither one can end up in the value of a field the user typed into. The
+ * validation-only constraints — {@literal minLength}, {@literal pattern},
+ * required — are deliberately absent: the browser commits a value that breaks
+ * them and leaves the field invalid, which is the state a validation test needs
+ * to reach. Alongside them sits the structural refusal of {@code null}, which a
+ * text input has no state for at all.
+ */
+final class TextInputConstraints {
+
+    private TextInputConstraints() {
+    }
+
+    /**
+     * Fails when the given value is {@code null} and the field has no null
+     * state to hold it, that is when its empty value is something else.
+     *
+     * @param field
+     *            the field the value is typed into
+     * @param value
+     *            the value to type
+     * @throws IllegalArgumentException
+     *             if the field cannot hold {@code null}
+     */
+    static void ensureValueIsNotNull(HasValue<?, ?> field, Object value) {
+        if (value == null && field.getEmptyValue() != null) {
+            throw new IllegalArgumentException(
+                    "Field doesn't allow null values");
+        }
+    }
+
+    /**
+     * Fails when the given value contains characters the user could not have
+     * typed into the component.
+     *
+     * @param component
+     *            the component the value is typed into
+     * @param value
+     *            the value to type
+     * @throws IllegalArgumentException
+     *             if the value is longer than {@literal maxlength} or contains
+     *             a character {@literal allowedCharPattern} filters out
+     */
+    static void ensureValueCanBeTyped(Component component, String value) {
+        if (value == null || value.isEmpty()) {
+            // There is nothing to type: emptying a field is always something
+            // the user can do, and a null value only gets this far on a field
+            // whose own empty value is null.
+            return;
+        }
+        ensureWithinMaxLength(component, value);
+        ensureCharactersAreAllowed(component, value);
+    }
+
+    private static void ensureWithinMaxLength(Component component,
+            String value) {
+        // The maxlength property is read off the element rather than through
+        // getMaxLength(), which TextField, TextArea, PasswordField and
+        // EmailField each declare separately instead of TextFieldBase, and
+        // which reports zero both for an unset limit and for a limit of zero.
+        // The element property is what the component itself branches on, in a
+        // private hasMaxLength(); a getter telling the two apart on
+        // TextFieldBase belongs upstream in vaadin/flow-components.
+        if (component.getElement().getProperty("maxlength") == null) {
+            return;
+        }
+        final int maxLength = (int) component.getElement()
+                .getProperty("maxlength", 0d);
+        // The browser ignores a negative maxlength as it ignores an unset one.
+        if (maxLength >= 0 && value.length() > maxLength) {
+            throw new IllegalArgumentException("Value '" + value + "' is "
+                    + value.length() + " characters long, but the field takes "
+                    + "at most " + maxLength
+                    + ". The browser truncates the characters over the limit, "
+                    + "so the user cannot produce this value.");
+        }
+    }
+
+    private static void ensureCharactersAreAllowed(Component component,
+            String value) {
+        if (!(component instanceof HasAllowedCharPattern field)) {
+            return;
+        }
+        final String allowedCharPattern = field.getAllowedCharPattern();
+        if (allowedCharPattern.isEmpty()) {
+            return;
+        }
+        final Pattern allowedChar;
+        try {
+            allowedChar = Pattern.compile(allowedCharPattern);
+        } catch (PatternSyntaxException e) {
+            // The browser only warns about a pattern it cannot compile and
+            // then lets every character through.
+            return;
+        }
+        // The pattern matches one character at a time, so it is applied per
+        // code point, the way the web component filters the keystrokes.
+        final OptionalInt rejected = value.codePoints()
+                .filter(codePoint -> !allowedChar
+                        .matcher(Character.toString(codePoint)).matches())
+                .findFirst();
+        if (rejected.isPresent()) {
+            throw new IllegalArgumentException("Value '" + value
+                    + "' contains the character '"
+                    + Character.toString(rejected.getAsInt())
+                    + "', which the allowed char pattern '" + allowedCharPattern
+                    + "' does not match. The browser "
+                    + "filters out such a keystroke, so the user cannot "
+                    + "produce this value.");
+        }
+    }
+}