How to Automate a Login Page with Selenium WebDriver

To automate a login page with Selenium WebDriver, start a browser session, open your test environment’s login page, locate the username and password fields, enter test credentials, click the login button, then wait for a stable, application-specific sign of successful authentication. Use explicit waits for fields and the post-login state; do not assume that page navigation alone means a JavaScript application is ready.

The example below uses Python. Replace the sample URL, selectors, credentials, and success condition with values from an application you are authorized to test. Selenium WebDriver is a browser automation interface standardized by the W3C; a language binding and browser-specific driver connect your script to the browser. See the Selenium WebDriver documentation.

1. Install Selenium and prepare a test account

Install the Python binding in your project environment:

python -m pip install selenium

Install or make available a supported browser such as Chrome or Firefox. Selenium’s browser-specific driver implementation communicates with that browser. Follow the current Selenium setup instructions for your environment and browser; avoid relying on a driver binary from an unrelated or incompatible browser version.

Use a dedicated test account and the secret/configuration mechanism approved by your project. Do not commit real credentials into source control or print them to logs. For example, provide these environment variables before starting the script:

TEST_LOGIN_URL=https://app.example.test/login
TEST_USERNAME=selenium-test-user
TEST_PASSWORD=replace-with-a-test-secret

The example targets a placeholder domain. Do not run it against an application unless you have authorization and test credentials.

import os

from selenium import webdriver
from selenium.common.exceptions import TimeoutException
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

login_url = os.environ["TEST_LOGIN_URL"]
username_value = os.environ["TEST_USERNAME"]
password_value = os.environ["TEST_PASSWORD"]

# Set this to a stable element that only appears after authentication.
success_selector = "[data-testid='account-menu']"

# Selenium Manager may assist with driver setup, depending on your Selenium
# version and environment. Configure a driver explicitly if your environment
# requires it.
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 15)

try:
    driver.get(login_url)

    username = wait.until(
        EC.visibility_of_element_located((By.NAME, "username"))
    )
    password = wait.until(
        EC.visibility_of_element_located((By.NAME, "password"))
    )

    username.send_keys(username_value)
    password.send_keys(password_value)

    submit = wait.until(
        EC.element_to_be_clickable((By.CSS_SELECTOR, "button[type='submit']"))
    )
    submit.click()

    # Replace with the application's actual authenticated-state signal.
    wait.until(
        EC.visibility_of_element_located((By.CSS_SELECTOR, success_selector))
    )

    print("Login reached the expected authenticated state.")

except TimeoutException as exc:
    # Keep diagnostics useful without exposing the password or other secrets.
    print(f"Login did not reach the expected state. Current URL: {driver.current_url}")
    raise

finally:
    driver.quit()

The selectors are examples, not universal locators. Inspect the application’s DOM and use stable attributes intended for testing where available, such as a test ID. The success selector should represent an authenticated state, such as an account menu or a page element available only after login.

3. Choose the right fields, button, and success condition

Locate the controls

Selenium supports locating elements by ID, name, CSS selector, XPath, and other strategies. Prefer a stable ID, name, or test-specific attribute when the application provides one. For example, if the page has id="email", use (By.ID, "email"); if it has name="password", use (By.NAME, "password").

A locator matching multiple elements can select the wrong control or fail to express which field you mean. Inspect the live DOM, including whether the form is inside an iframe, and make the locator specific enough for the intended field.

Wait for interaction readiness

Wait for a field to be visible before typing and for the submit control to be clickable before clicking. These conditions are more useful than checking document readyState alone: a JavaScript application may still be rendering or revealing interactive controls after document loading has completed.

After clicking, wait for a condition tied to the actual outcome: a user-specific account element, authenticated page content, a success message, or a known URL transition. An HTTP-style redirect is not the only valid signal, and a changed URL alone may not prove that the expected account state is present. Pick an assertion that matches the behavior your test is meant to cover.

For other cases, Selenium’s expected conditions can wait for presence, visibility, text, title, or URL conditions. See Selenium’s waiting strategies and Python expected conditions.

4. Run the script and keep the session isolated

Set the test URL and test-only credentials using your project’s approved configuration.
Update the username, password, submit-button, and success-state selectors to match the test application.
Run the script from the same environment where Selenium and the browser are installed.
Check the final assertion and current URL if it times out; never diagnose by printing the password.
Keep driver.quit() in cleanup so the browser session closes even after a failure.

Selenium’s first-script tutorial demonstrates the general sequence of opening a page, finding elements, entering text, clicking, reading a result, and quitting the driver: First script.

5. Handle asynchronous pages and authentication variations

Single-page applications

A navigation command finishing does not guarantee that a single-page application has rendered the login form or completed its post-login updates. Wait for the specific field or authenticated-state element needed next. Avoid treating a fixed delay as proof of readiness.

Validation errors and rejected credentials

If the application rejects a login, the form may remain visible and show an error. In tests of invalid credentials, wait for the expected error message instead of the authenticated-state element. In a successful-login test, a timeout on the success element should be investigated alongside validation messages and the current URL.

Multi-factor authentication

If the flow requires MFA, decide whether the test is specifically covering that flow. Use a supported test environment or test mechanism approved by the application team; do not try to bypass real security controls. A login test should wait for the actual expected next step, which might be an MFA prompt rather than the account page.

Frames and alternate browsing contexts

If a field appears in an iframe, switch into the correct frame before locating and interacting with it, then switch back to the default content when appropriate. A selector that looks correct in the top-level DOM cannot locate an element in a different browsing context.

Keep waits predictable

Use explicit waits for concrete conditions. Selenium warns against mixing implicit and explicit waits because their combined timing can be unpredictable. Arbitrary sleeps can be too short to work or unnecessarily long on a fast run. See Selenium’s waiting strategies.

Drive the login UI when the test is intended to cover authentication behavior: form validation, login redirects, MFA prompts, or the user-visible sign-in flow. If a test only needs to begin in an authenticated state, Selenium recommends creating that state through another mechanism, such as an API login followed by setting a cookie, rather than repeating browser login for every test. Selenium’s guidance is explicit: “Selenium should not be used to prepare a test case.”

Test need	Suitable setup	Why
Verify login form and authentication behavior	Automate the UI flow	The browser exercises the behavior users encounter.
Test an authenticated feature unrelated to login	Use an approved API or test-state setup, then establish the session	Avoid repeating unrelated login work in every test.
Capture a public page without signing in	Use a screenshot tool or API suited to public pages	A browser login flow may be unnecessary for a public URL.

The speed and stability benefit of avoiding repeated UI setup follows Selenium’s guidance. UI login remains valuable where authentication itself is under test.

7. Troubleshoot common failures

Symptom	Likely cause	Fix
Driver or browser session will not start	Browser, Selenium binding, and driver setup are missing or incompatible.	Confirm the browser is installed, update Selenium, and follow its current browser-specific driver setup guidance.
`NoSuchElementException`	The selector is wrong, the element has not rendered, or it is in a frame.	Inspect the current DOM, wait for the expected state, verify the selector, and switch browsing context if needed.
`ElementNotInteractableException` or click interception	The control is hidden, disabled, covered, or not yet ready.	Wait for visibility or clickability, inspect overlays, and verify the intended element is enabled and in view.
Wait times out after clicking login	Credentials were rejected, the success selector is wrong, the app is still rendering, or another step such as MFA is required.	Inspect the visible state and current URL; wait for the correct outcome for this test, and keep credentials out of diagnostics.
The page loads but the form cannot be found	Document loading finished before client-side rendering, or the form is in an iframe.	Wait for the specific field and inspect frames and shadow/context boundaries in the application.
Tests fail intermittently with inconsistent timeout duration	Fixed sleeps or mixed implicit and explicit waits make timing fragile.	Remove implicit waits when using explicit waits; wait on the condition required at each step.
Login works locally but not in a shared runner	The runner may lack the browser, driver setup, environment variables, network access, or a compatible display/headless configuration.	Check runner dependencies and secret configuration, then configure browser options for that environment.

8. Reliability, performance, and cost considerations

Reliability: Stable selectors, explicit state waits, test-only accounts, and cleanup reduce avoidable flakiness. A single test should assert the outcome it is designed to cover.
Performance: Browser startup, page loading, and repeated authentication add time. Reuse an authenticated setup mechanism for tests that do not exercise login itself, as Selenium’s test-practices guidance recommends.
Secrets: Read credentials from the approved secret or configuration store. Avoid including them in source, screenshots, command output, or failure logs.
Cost: Selenium is an open-source browser automation project, but running browsers still uses compute and can incur infrastructure or hosted-runner costs. Budget depends on your environment and test volume; no universal per-login cost applies.

Or skip the browser setup

If your goal is a screenshot of a public page rather than testing its login behavior, ScreenshotNeo is a website screenshot API and MCP server. Its API takes a URL and returns an image or PDF; see the API documentation.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Frequently asked questions

Can Selenium log in to any website with one script?

No. Selectors, success conditions, and authentication steps are specific to the application. Use a test environment and adapt the script to its DOM and approved authentication flow.

Should I use XPath or CSS selectors?

Either can locate elements. Choose the simplest stable locator the application provides, such as an ID, name, or test attribute; use CSS or XPath when the DOM requires a more specific relationship.

Yes, when the browser session must authenticate or the login flow is what you need to test. For a public page screenshot, a screenshot API can avoid setting up a browser session; ScreenshotNeo accepts a URL in one GET request.

Why does Selenium say the page loaded when the form is still missing?

Document readiness does not guarantee that JavaScript-driven controls have been rendered. Wait for the specific form element or state your next action requires.