How web forms work

What a form is#

<form action="/signup" method="post">  <input name="name" type="text" required>  <select name="plan"><option value="free">Free</option><option value="pro">Pro</option></select>  <input name="terms" type="checkbox">  <button type="submit">Create account</button></form>

The action is where to send, the method is how. Each control with a name is one entry. Three rules explain surprises in tests:

• A control without a name is not sent.
• A disabled control is not sent, although a read-only one is.
• An unchecked checkbox or radio button is not sent at all: the server sees no entry, not “off”. A checked one with no value sends on.

What the browser does between the click and the request.

GET and POST#

Never put a password or token in a GET form: it lands in the history, the server log and the Referer header. After a successful POST, well-built sites answer with a redirect to a GET page, so a reload does not resubmit the form; a test should wait for the new address rather than read the page it just left.

How the body is encoded#

The enctype attribute chooses the format.

POST /signup HTTP/1.1Content-Type: application/x-www-form-urlencodedname=Ada+Lovelace&plan=pro&terms=on

application/x-www-form-urlencoded is the default: name=value pairs joined by &, with spaces as + and other characters as % and two hex digits.

POST /profile HTTP/1.1Content-Type: multipart/form-data; boundary=----b0und4ry------b0und4ryContent-Disposition: form-data; name="name"Ada------b0und4ryContent-Disposition: form-data; name="photo"; filename="ada.png"Content-Type: image/png(the bytes of the file)------b0und4ry--

multipart/form-data sends each field as its own part, separated by a boundary string, and is required for file uploads because a part can hold raw bytes. A third type, text/plain, is rarely used. Many modern pages skip all of this: JavaScript reads the fields and sends JSON with fetch, and the form is only a way to collect them. See frontends, backends and APIs.

Input types#

The type attribute decides the keyboard on a phone, the built-in checks and the widget the browser draws.

textarea is a multi-line text field, select a dropdown (with option entries, and multiple for several), and datalist offers suggestions for a text field.

Constraint validation#

The browser checks fields before it sends anything, using attributes: required, pattern (a regular expression), min and max, minlength and maxlength, step, and the type itself. A failing field stops the submit and the browser shows a small message next to it.

For tests that matters twice:

• The message bubble is drawn by the browser, not part of the page, so no selector finds it. Read the field’s validationMessage and validity properties instead, or check that the field matches the :invalid selector.
• The novalidate attribute on the form turns the checks off, and any script can call checkValidity() or reportValidity() or set its own text with setCustomValidity().

File uploads#

A page cannot choose a file for the user: input type="file" lets only the person pick, through the system’s file dialog. That dialog is not part of the web page, so automation cannot click through it.

The way around it is to skip the dialog: give the input element itself the path of the file.

• With WebDriver, sending the absolute path as “keys” to the file input does it.
• With the DevTools Protocol, the command DOM.setFileInputFiles sets the files of the input.

Two practical points: the input is often hidden behind a styled button or a drag-and-drop area, but it is still in the page, so aim at the input element and not at the button; and accept and multiple attributes are only hints for the dialog, so the page’s own script or the server decides what is really allowed.

Autofill and password managers#

Browsers fill fields from saved data. They decide what a field is from the autocomplete attribute (username, current-password, new-password, email, one-time-code, cc-number, and others) and from its name and label. In tests this causes two problems: a saved login filling a field the test then types into, and a prompt such as “Save password?” in the way. A fresh profile per run avoids both, and a good suite sets the autocomplete values so that the real browser and the test agree on what each field means.

CSRF tokens#

A form that changes data usually contains a hidden token (often named something like _csrf or authenticity_token) tied to the user’s session, which the server checks on submit. A hostile page cannot read it, so it cannot forge the form. See web security for the attack.

For a test this means: never hard-code the token, because it changes per session (and often per page load). A test that fills a real page gets a valid token for free. A test that posts the request directly must first load the form with the same cookie jar, read the token out of the page, and send it back.

Custom widgets and framework-controlled inputs#

Many sites replace the native controls with their own.

• Styled dropdowns are usually a div that opens a list, not a select. A “select an option” command will not work. Click to open, then click the option, as a user would. Good widgets expose ARIA roles such as combobox, listbox and option that make selectors reliable.
• Date pickers, rich-text editors (an element with contenteditable) and masked inputs (a phone number that reformats as you type) have their own code behind them.
• Autocomplete boxes wait for typing, ask a server and show results later. Type, then wait for the list, then click.

The hardest case is the framework-controlled input. In React, Vue, Angular and similar frameworks (see frameworks and the DOM) the field’s value lives in the framework’s state; the framework draws it into the field and listens for input and change events to learn about edits.

That has a consequence. If a script sets the field’s value property directly, the screen shows the new text, but no event fired, the state still holds the old value, and the next redraw puts the old text back (or the submit button stays disabled). The fix is to produce the events the page waits for:

1. Type like a user: key by key. Each key gives the page keydown, input and keyup, and masks and live validation work.
2. Insert text in one step: faster, and the page still receives a genuine input event, but not the per-key events. Fine for plain fields, not for masks.
3. Set the value and dispatch events: for controls that ignore the keyboard, such as a range slider, set the value and then dispatch bubbling input and change events. Some frameworks need the browser’s own value setter used first.

Also remember blur: many forms validate when you leave a field. After typing, move the focus (press Tab, or click elsewhere) before you expect the error text. For more on events and waiting, see JavaScript, events and waiting.

How seleniumbase-rs uses it#

sb.type_text("#email", "ada@example.com").await?;sb.select_option_by_text("#plan", "Pro").await?;sb.check_if_unchecked("#terms").await?;sb.choose_file("input[type=file]", "fixtures/photo.png").await?;sb.submit("#email").await?;           // submits the form that holds #email

page.locator("#email").fill("ada@example.com").await?;page.locator("#phone").type_text("5551234567").await?;        // a masked field: per-keypage.locator("#volume").set_value("70").await?;                 // a range sliderpage.locator("#terms").check().await?;

Where to go next#