How to Test Google Places Autocomplete with Playwright: Complete 2026 Guide

1. Why Testing Google Places Autocomplete Is Harder Than It Looks

Google Places Autocomplete looks simple on the surface: a user types into an input, a dropdown of predictions appears, and they click one. Under the hood, though, there are several layers of asynchronous behavior that make reliable end-to-end testing genuinely difficult. The autocomplete widget debounces keystrokes (typically 200 to 300 milliseconds), fires a network request to the Autocomplete API, waits for the response, renders a prediction list, and then waits again for the user to select an item before firing a completely separate Place Details request to fetch the full address components and geometry.

The prediction list itself is the first trap. It is rendered by the Google Maps JavaScript SDK in a detached container that lives outside your application's DOM tree. The .pac-container element is appended directly to document.body and positioned absolutely, which means your usual component-scoped selectors will not find it. The items inside use .pac-item class names, not semantic roles or labels, so accessible selectors like getByRole do not work out of the box.

There are five structural reasons this flow resists automation. First, the prediction list timing depends on network latency and the debounce interval, so any fixed waitForTimeout will either be too slow in CI or too fast on a congested network. Second, session tokens tie a sequence of autocomplete requests to a single Place Details call for billing purposes, and if your test inadvertently creates multiple sessions, your billing tests and your functional tests will give different results. Third, the Place Details response contains structured address components (street number, route, locality, administrative area, postal code, country) that your app must parse correctly; a test that only checks the formatted address string misses parsing bugs. Fourth, many implementations update a map marker or viewport when a place is selected, and verifying that the map actually panned requires reading the Google Map instance state. Fifth, Google enforces per-key quotas and rate limits; a test suite that runs 50 autocomplete queries in rapid succession can exhaust the daily quota for a test API key.

A reliable autocomplete test suite must handle all of these layers. The sections below walk through each scenario you need, with runnable Playwright TypeScript you can paste into a real project.

2. Setting Up a Reliable Test Environment

Before writing test scenarios, you need a stable environment that isolates your tests from production billing and quota limits. Google Maps Platform requires an API key with the Places API (New) or Places API enabled. Create a separate project in the Google Cloud Console dedicated to testing. Restrict the key to localhost and your CI domain so it cannot be abused, and set a daily quota cap that is generous enough for your full test suite but low enough to prevent runaway costs.

Environment Variables

Playwright Configuration for Places Autocomplete

The Google Maps JavaScript SDK makes requests to maps.googleapis.com from the browser. Playwright needs to allow these cross-origin requests and handle the asynchronous script loading. Set a generous action timeout because prediction responses depend on network latency, and configure a custom fixture to intercept Places API responses when you want deterministic results.

Route Interception for Deterministic Tests

For CI environments where you cannot rely on live Google API responses (or want to avoid quota usage), intercept the Autocomplete and Place Details endpoints and return canned responses. This gives you full control over prediction timing, response content, and error simulation.

3. Scenario: Basic Prediction List Appears

The most fundamental scenario for any Places Autocomplete integration is confirming that the prediction dropdown appears when a user types into the address input. This is your smoke test. If predictions do not appear, every downstream feature (address selection, form population, map updates) is broken. The challenge is that the prediction list is asynchronous and depends on the Google Maps SDK loading, the API key being valid, and the debounce timer completing before any predictions appear.

import { test, expect } from '@playwright/test';

test('prediction list appears', async ({ page }) => {
  await page.goto('/address-form');
  await page.waitForFunction(() =>
    typeof google !== 'undefined'
    && typeof google.maps.places !== 'undefined'
  );

  const input = page.getByPlaceholder('Enter your address');
  await input.click();
  await input.pressSequentially('1600 Amphitheatre', { delay: 50 });

  const pacContainer = page.locator('.pac-container');
  await expect(pacContainer).toBeVisible({ timeout: 5_000 });

  const predictions = pacContainer.locator('.pac-item');
  await expect(predictions.first()).toBeVisible();
  expect(await predictions.count()).toBeGreaterThanOrEqual(1);
});

4. Scenario: Selecting a Prediction and Parsing Address Components

Clicking a prediction item triggers the most important part of the flow: the Place Details API call. When a user selects a prediction, the Google Maps SDK calls getDetails() with the place_id from the selected prediction and returns structured address components. Your application must parse these components correctly to populate form fields like street, city, state, and ZIP code. This scenario tests both the selection interaction and the downstream parsing logic.

import { test, expect } from '@playwright/test';

test('selecting prediction populates fields', async ({ page }) => {
  await page.goto('/address-form');
  await page.waitForFunction(
    () => typeof google?.maps?.places !== 'undefined'
  );

  const input = page.getByPlaceholder('Enter your address');
  await input.click();
  await input.pressSequentially('1600 Amphitheatre Parkway', { delay: 50 });

  const pacContainer = page.locator('.pac-container');
  await expect(pacContainer).toBeVisible({ timeout: 5_000 });
  await pacContainer.locator('.pac-item').first().click();

  await expect(page.getByLabel('Street')).toHaveValue(/1600 Amphitheatre/);
  await expect(page.getByLabel('City')).toHaveValue('Mountain View');
  await expect(page.getByLabel('State')).toHaveValue('CA');
  await expect(page.getByLabel('ZIP Code')).toHaveValue('94043');
  await expect(page.getByLabel('Country')).toHaveValue('US');
});

5. Scenario: Session Token Lifecycle

Google Places Autocomplete uses session tokens to group a series of autocomplete requests with a final Place Details request into a single billing session. When the AutocompleteSessionToken is used correctly, all prediction requests within the session are free and you only pay for the Place Details call. If your application creates a new session token on every keystroke or forgets to pass the token to getDetails(), you get billed per prediction request instead of per session. This can multiply your Places API costs by 10x or more.

6. Scenario: Map Pin Update After Selection

Many applications display a Google Map alongside the autocomplete input. When the user selects a prediction, the map should pan to the selected location and place a marker at the correct coordinates. Testing this requires reading the Google Map instance's internal state (center position and zoom level) through the browser's JavaScript context. You cannot rely solely on visual inspection because a map that looks correct at a glance might be off by several hundred meters.

7. Scenario: Error States and Rate Limiting

Your application must handle Places API errors gracefully. Common failure modes include an invalid or expired API key, exceeding the daily quota, network timeouts, and the ZERO_RESULTS response when the user types a nonsensical address. A robust test suite covers these error paths to ensure the user sees a helpful message instead of a broken, empty dropdown or a silent failure.

8. Scenario: Mobile Viewport and Touch Interactions

The Places Autocomplete dropdown behaves differently on mobile viewports. The .pac-container is positioned absolutely and can overflow the viewport on narrow screens. Touch interactions may require different handling than mouse clicks, and the virtual keyboard on mobile devices pushes the viewport up, potentially hiding the prediction list. Testing with a mobile viewport ensures your autocomplete experience works for the majority of users who are on phones.

import { test, expect, devices } from '@playwright/test';
test.use(devices['iPhone 13']);

test('autocomplete works on mobile', async ({ page }) => {
  await page.goto('/address-form');
  await page.waitForFunction(
    () => typeof google?.maps?.places !== 'undefined'
  );

  const input = page.getByPlaceholder('Enter your address');
  await input.tap();
  await input.pressSequentially('1600 Amphitheatre', { delay: 80 });

  const pacContainer = page.locator('.pac-container');
  await expect(pacContainer).toBeVisible({ timeout: 5_000 });

  const containerBox = await pacContainer.boundingBox();
  const viewport = page.viewportSize();
  expect(containerBox!.x + containerBox!.width)
    .toBeLessThanOrEqual(viewport!.width);

  await pacContainer.locator('.pac-item').first().tap();
  await expect(page.getByLabel('City')).not.toHaveValue('');
});

9. Common Pitfalls That Break Autocomplete Test Suites

These are real problems sourced from Google Maps Platform GitHub issues, Stack Overflow threads, and production post-mortems. Every one of them has broken a real team's test suite.

The pressSequentially() versus fill()distinction is the single most common reason autocomplete tests fail. Playwright's fill() method dispatches an input event directly on the element, which works for standard form fields. The Google Maps SDK, however, attaches event listeners to keydown, keyup, and keypress events. Without those events, the SDK never knows the user is typing and never fetches predictions.

Use pressSequentially() with a delayof 50 to 100 milliseconds to simulate real typing. This fires individual key events for each character and gives the SDK's debounce logic time to trigger the API call.

10. Writing These Scenarios in Plain English with Assrt

Every scenario above required careful handling of the .pac-container selector, pressSequentially() instead of fill(), explicit waits for async API responses, and knowledge of Google Maps SDK internals. Assrt lets you write the same scenarios in plain English. The Assrt compiler generates the correct Playwright TypeScript with all the SDK-specific patterns built in.

Here is the address selection and parsing scenario from Section 4, rewritten as an Assrt scenario file alongside the session token and error handling tests.

Assrt compiles each scenario block into the same Playwright TypeScript you saw in the preceding sections, committed to your repo as real tests you can read, run, and modify. When Google updates the Maps JavaScript SDK and changes the .pac-container structure or the autocomplete API response format, Assrt detects the failure, analyzes the new DOM, and opens a pull request with the updated selectors and assertions. Your scenario files stay untouched.

Start with the basic prediction scenario. Once it is green in your CI, add the address parsing test, then the session token verification, then the error handling scenarios, then the mobile viewport test. In a single afternoon you can have complete Google Places Autocomplete coverage that most production applications never manage to achieve by hand.