Puppeteer AutofillAddressField: Autofill Address Forms

Short answer: Puppeteer exposes AutofillAddressField as a vocabulary of supported address field names, but its documented ElementHandle.autofill() method currently supports credit-card data only. For address autofill in automated tests, Chromium has a separate experimental DevTools Protocol (CDP) Autofill domain. If you only need to inspect how Chrome recognizes a form, use the Chrome DevTools Autofill panel.

The distinction matters: an enum describing address fields does not guarantee that Puppeteer’s convenience method can fill them. Puppeteer’s current API reference is version 25.12.0; check your installed Puppeteer and browser versions before relying on any autofill behavior. [Puppeteer API index] [ElementHandle.autofill()]

1. What AutofillAddressField means

AutofillAddressField names address fields that can appear in autofill data. It is a type-level vocabulary, not a method call, runtime capability guarantee, or evidence that a particular field will be recognized on a page. Puppeteer’s documented ElementHandle.autofill() accepts AutofillData and returns a promise, but its remarks specify credit-card autofill in Chrome’s new headless and headful modes. It may throw if the form cannot be autofilled.

So, if your question is “Can I call elementHandle.autofill() with an address object?”, the documented answer is no: the current method documentation does not say it supports address data. Use the protocol route below if your test requires Chrome’s address autofill behavior.

2. Choose the right address-form workflow

Approach	Best for	Address support	Trade-off
Puppeteer ElementHandle.autofill()	Documented convenience API	Current docs describe credit cards only	Do not treat the address enum as support for address filling.
Chromium CDP Autofill domain	Automated address-autofill tests in Chromium	Experimental address trigger and test-address setup	Lower-level protocol; version and browser compatibility matter.
Chrome DevTools Autofill panel	Interactive diagnosis of detection and predictions	Address information	Manual visual inspection, not a Puppeteer automation API.

Puppeteer uses Chrome DevTools Protocol by default to automate Chrome and WebDriver BiDi by default for Firefox. Puppeteer releases are paired with specific browser releases, so record both versions when debugging protocol behavior. [Puppeteer FAQ]

3. Make your address form recognizable

Browser autofill depends on field semantics and browser recognition. Use appropriate HTML input types and autocomplete tokens, stable labels, and a real form structure. For example:

<form>
  <label for="given-name">First name</label>
  <input id="given-name" name="given-name" autocomplete="given-name">

  <label for="family-name">Last name</label>
  <input id="family-name" name="family-name" autocomplete="family-name">

  <label for="street-address">Street address</label>
  <input id="street-address" name="street-address" autocomplete="street-address">

  <label for="address-level2">City</label>
  <input id="address-level2" name="address-level2" autocomplete="address-level2">

  <label for="address-level1">State or region</label>
  <input id="address-level1" name="address-level1" autocomplete="address-level1">

  <label for="postal-code">Postal code</label>
  <input id="postal-code" name="postal-code" autocomplete="postal-code">

  <label for="country">Country</label>
  <input id="country" name="country" autocomplete="country-name">
</form>

Address formats vary by country. Do not assume every locale has a state, postal code, or the same street-address layout. Test optional fields, localized labels, and country-specific form variants. The protocol distinguishes fields filled using an HTML autocomplete attribute from fields filled through autofill heuristics, so correct semantics give the browser useful signals without guaranteeing recognition.

4. Automated address filling through Chromium CDP

Chromium’s DevTools Protocol defines an experimental Autofill domain. Its trigger command accepts an anchor form field and address data (or credit-card data; the two are mutually exclusive). Address data is an array of name/value fields. The protocol also defines setAddresses for test addresses and an addressFormFilled event. The supplied data is not saved by the protocol. [Chromium DevTools Protocol Autofill definition]

The following is a runnable Node.js example using Puppeteer’s CDP session. It sets a test address, enables the domain, finds an anchor field, triggers address autofill, and prints the resulting field values. The domain is experimental; confirm the command schema against the protocol supported by your installed Chrome build.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: true });
try {
  const page = await browser.newPage();
  await page.goto('http://localhost:3000/address-form', {
    waitUntil: 'domcontentloaded',
  });

  const client = await page.createCDPSession();
  await client.send('Autofill.enable');
  await client.send('Autofill.setAddresses', {
    addresses: [{
      fields: [
        { name: 'NAME_FULL', value: 'Alex Example' },
        { name: 'ADDRESS_HOME_LINE1', value: '123 Example Street' },
        { name: 'ADDRESS_HOME_CITY', value: 'Springfield' },
        { name: 'ADDRESS_HOME_STATE', value: 'CA' },
        { name: 'ADDRESS_HOME_ZIP', value: '90210' },
        { name: 'ADDRESS_HOME_COUNTRY', value: 'US' },
      ],
    }],
  });

  const anchor = await page.$('input[autocomplete="given-name"]');
  if (!anchor) throw new Error('Address form anchor field was not found');

  const { backendNodeId } = await client.send('DOM.describeNode', {
    objectId: (await anchor.evaluateHandle(el => el)).remoteObject().objectId,
  });
  await client.send('Autofill.trigger', {
    fieldId: backendNodeId,
    address: {
      fields: [
        { name: 'NAME_FULL', value: 'Alex Example' },
        { name: 'ADDRESS_HOME_LINE1', value: '123 Example Street' },
        { name: 'ADDRESS_HOME_CITY', value: 'Springfield' },
        { name: 'ADDRESS_HOME_STATE', value: 'CA' },
        { name: 'ADDRESS_HOME_ZIP', value: '90210' },
        { name: 'ADDRESS_HOME_COUNTRY', value: 'US' },
      ],
    },
  });

  const values = await page.$$eval('input', inputs =>
    inputs.map(input => ({ name: input.name, value: input.value }))
  );
  console.log(values);
} finally {
  await browser.close();
}

Protocol-version note: CDP command schemas and required identifiers can vary by Chromium version. In some protocol revisions, Autofill.trigger uses a DOM node identifier and address structure as described by the schema, while the exact field names accepted are defined by Chromium’s protocol. Consult the protocol definition bundled with the browser you launch. Keep the example aligned with that schema; it is not a promise that every Puppeteer/Chrome pair accepts identical payloads.

In a robust test, subscribe to Autofill.addressFormFilled before triggering so the event cannot arrive before the listener is attached:

const filled = new Promise(resolve => {
  client.once('Autofill.addressFormFilled', resolve);
});
// Send Autofill.trigger here, then inspect: const event = await filled;

The event reports filled fields, including HTML type, ID, name, value, inferred autofill type, filling strategy, frame ID, and backend node ID. Use those details to distinguish a field matched via its declared autocomplete value from one matched heuristically.

5. Diagnose recognition in Chrome DevTools

For manual investigation, Chrome DevTools has an Autofill panel for address forms. It shows detected page fields, predicted autofill values, and values Chrome inserted. The guide describes using test address data without saving personal address information: focus a form field and select a test option. The panel is for diagnosis, not a Puppeteer API, and the guide’s interface instructions may change. [Chrome DevTools Autofill guide]

1. Open the page and DevTools, then open the Autofill panel.
2. Review which fields Chrome detected and the predictions shown for them.
3. Use test address data and inspect the inserted values.
4. Correct labels, input names, types, and autocomplete tokens when detection is wrong, then repeat with the relevant locale and form variant.

Chrome’s address-saving setting is called “Addresses and more” in the referenced guide. For reproducible tests, prefer test data over personal address details.

6. Reliability, performance, and test design

• Pin the browser pair: Puppeteer is tightly bundled with a browser release. Record Puppeteer version, browser version, and headless/headful mode in failures.
• Wait for the form: Navigate to a meaningful readiness condition before querying the anchor field. A selector wait is more reliable than a fixed sleep for dynamically rendered forms.
• Use isolated test data: Keep deterministic synthetic address values and avoid relying on a developer’s saved personal profiles.
• Test recognition separately from submission: Autofill populating controls does not prove application validation, address normalization, or checkout submission works.
• Cover locale and layout variants: Optional fields, split street lines, and country-specific forms can change which fields are present.
• Expect experimental protocol change: CDP Autofill is explicitly experimental. Treat protocol failures after browser upgrades as a compatibility signal, and verify against the matching protocol schema.
• Cost: This workflow runs your own browser automation; the cited Puppeteer and protocol documentation does not specify a per-autofill charge. Account for your own browser infrastructure and CI runtime.

7. Troubleshooting

Symptom	Likely cause	What to do
ElementHandle.autofill() does not fill address inputs	The documented method currently supports credit-card information only.	Use Chromium’s experimental CDP Autofill domain for address tests, or the DevTools panel for diagnosis.
“Form cannot be autofilled” or no fields change	The page fields were not recognized, the wrong anchor was selected, or the form was not ready.	Wait for the form, choose an address field within it, check field semantics and inspect Chrome’s Autofill panel predictions.
CDP reports an unknown command or parameter	The launched Chromium protocol schema differs from the example or Autofill domain support.	Check the protocol definition for that browser build and adapt command names and payload shape; verify Puppeteer/browser pairing.
Only some values appear	Fields may be absent, ambiguous, unsupported for the locale, or recognized by different strategies.	Inspect the filled-field event and DevTools predictions; check each field’s autocomplete token, name, type, and visibility.
The field handle is missing	Selector mismatch, delayed rendering, iframe, or changed markup.	Wait for a selector, verify the frame containing the form, and select an anchor inside the target form.
Tests pass locally but fail in CI	Different browser version, headless mode, or timing/readiness behavior.	Pin compatible versions, log runtime details, and make readiness conditions explicit.

8. Or skip the browser setup

If your immediate goal is a rendered page image rather than exercising browser autofill, ScreenshotNeo is a website screenshot API and MCP server. One GET request captures a URL as PNG, JPEG, WebP, or PDF. It does not fill forms or replace an autofill test. The API documentation covers the request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are never billed, and response headers indicate the page verdict and billing status. Its MCP server provides screenshot tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, no card required.

9. FAQ

Does AutofillAddressField fill a form by itself?

No. It names supported address field names; it is not a callable filling method.

Can I use this address workflow in Firefox?

The described Autofill domain is Chromium’s DevTools Protocol functionality. Puppeteer uses WebDriver BiDi by default for Firefox; do not assume Chromium’s Autofill commands apply there.

Does the protocol save the address?

The protocol definition says the supplied address or card data is not saved.

Should I test real customer addresses?

Use synthetic test address data where possible, especially for repeatable automation and debugging.