File Uploads, Downloads, Cookies, Storage, and Session State: Core Concepts and Mental Model

1. The practical problem: “session state” is not one thing

A browser test can pass locally and fail in CI even when locators and waits are correct. The hidden cause is often ownership: the upload file exists on the test runner but not on the remote browser host; a download lands in yesterday's directory; a cookie belongs to a different host; localStorage survives because a profile was reused; or a test assumes deleting cookies also deletes every authentication/session artifact.

Chapter 10 taught that DOM state has boundaries. Chapter 11 applies the same discipline to browser-held state and filesystem state.

2. Mental model: ownership and transport

flowchart TD
  T[Test process] -->|absolute local path| F[Upload file]
  T --> W[WebDriver session]
  F --> I[input type=file]
  W --> B[Browser context]
  B --> A[AUT origin]
  A --> C[Cookies: domain/path/expiry/sameSite]
  A --> LS[localStorage: origin-scoped]
  A --> SS[sessionStorage: origin + top-level context]
  B --> P[Browser profile / cache / preferences]
  B --> D[Browser download manager]
  D --> DD[Per-test download directory]
  W -. Remote/Grid .-> R[Remote browser host]
  T -. file detector transfer .-> R
  R -. downloadable-file API when enabled .-> T

The test process owns generated input files and evidence. The browser owns its current profile, cookie jar, storage areas, and download manager. The AUT origin determines which cookies and Web Storage entries are visible. A remote/Grid session introduces another machine boundary: the path C:\work\input.txt on the runner is not automatically a path on the node.

3. State stores are different contracts

The following table organizes the key choices and evidence for State stores are different contracts. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

4. Upload semantics: Selenium does not drive the OS chooser

The supported WebDriver technique is to locate an actual HTML file input and send an absolute path. Selenium deliberately avoids automating the native file picker.

from pathlib import Path
from selenium.webdriver.common.by import By

upload_path = Path("input.txt").resolve()
assert upload_path.is_file()
driver.find_element(By.CSS_SELECTOR, 'input[type="file"]').send_keys(str(upload_path))

For local WebDriver, the browser and test code run on the same machine boundary, so the path is directly usable. With Python RemoteWebDriver, the default LocalFileDetector recognizes a local file path and supports transfer to the remote end. The engineering rule is still: never assume the remote node can directly see the runner's filesystem path.

5. Download semantics: browser-managed output is not a normal WebDriver element

A download leaves DOM interaction and enters browser/file state. For the mandatory Chromium-local path, this chapter uses a unique per-test directory configured before session creation, then verifies the resulting bytes from the test process.

Selenium also exposes remote downloadable-file commands when downloads are enabled for a RemoteWebDriver session. Those commands solve a different problem: transferring a completed browser download from the remote node back to the test runner. They do not turn browser download progress into a portable DOM-style synchronization primitive.

6. Cookies: host/path/security metadata matters

A cookie is not just a name/value pair. WebDriver accepts attributes such as path, domain, secure, httpOnly, expiry, and sameSite. To add a host-scoped test cookie safely, navigate to the target origin first and omit a domain unless the scenario specifically requires one.

driver.get("http://127.0.0.1:8776/")
driver.add_cookie({"name": "academy_mode", "value": "synthetic", "sameSite": "Lax"})
print(driver.get_cookie("academy_mode"))

Trying to add a cookie for an unrelated domain can raise InvalidCookieDomainException. That is a scope error, not a reason to disable browser security.

7. Web Storage is origin-scoped and not a W3C WebDriver command set

localStorage and sessionStorage belong to the page origin. Current Selenium guidance treats their old dedicated command surfaces as deprecated because Web Storage is not part of W3C WebDriver. When a test must inspect this application state, use a narrow page-context script and keep it separate from UI interaction.

driver.get("http://127.0.0.1:8776/")
local_count = driver.execute_script("return window.localStorage.length")
session_count = driver.execute_script("return window.sessionStorage.length")
print("storage_counts", local_count, session_count)

8. Profile state is broader than cookies

A browser profile can contain cookies, local storage, caches, preferences, service-worker state, history, downloads, credentials, extensions, and browser-specific data. Therefore delete_all_cookies() does not mean “fresh browser.” For deterministic tests, prefer a new WebDriver session and a disposable profile rather than a personal or shared profile.

9. Read-only inspection before mutation

The following example makes the Read-only inspection before mutation behavior concrete. Read it with the stated assumptions, then compare its observable output or state changes with the explanation that follows.

import selenium
from selenium import webdriver

URL = "http://127.0.0.1:8776/"
driver = webdriver.Chrome()
try:
    driver.get(URL)
    caps = driver.capabilities
    snapshot = {
        "selenium": selenium.__version__,
        "session_id": driver.session_id,
        "browser": caps.get("browserName"),
        "browser_version": caps.get("browserVersion"),
        "url": driver.current_url,
        "title": driver.title,
        "cookie_names": [c["name"] for c in driver.get_cookies()],
        "local_storage_keys": driver.execute_script("return Object.keys(window.localStorage)"),
        "session_storage_keys": driver.execute_script("return Object.keys(window.sessionStorage)"),
    }
    print(snapshot)
finally:
    driver.quit()

The snapshot proves current browser/session/origin state without modifying it. In production evidence, record names and counts rather than secret values.

10. Credentials, PII, and artifact boundaries

Profiles and downloads are high-risk evidence sources because they can contain tokens, customer exports, email addresses, or generated documents. Mandatory labs use synthetic text only. Production automation should classify which files are retained, redact sensitive values from logs, restrict artifact access, and set retention limits.

11. DevOps connection: isolation makes reruns meaningful

Parallel CI depends on independent download directories, independent profile/session state, and input files with deterministic provenance. If retry 2 can consume retry 1's cookie or file, the rerun is not evidence about the same test—it is a different experiment.

12. Summary and next step

Uploads, downloads, cookies, Web Storage, and browser profiles are separate state stores. Reliable automation specifies where each lives, how it crosses local/remote boundaries, what proves a change occurred, and how cleanup restores isolation.

Knowledge check

Official references and version notes

• Selenium 4.47 release notes — stable baseline pinned for this chapter.
• Selenium downloads — current stable bindings and Selenium Server/Grid versions.
• File upload — use a file input and send the full path; do not automate the OS chooser.
• Working with cookies — WebDriver cookie create/read/delete semantics.
• Python RemoteWebDriver API — LocalFileDetector default plus remote downloadable-file methods.
• Python common Options API — enable_downloads capability surface.
• File downloads guidance — browser-triggered downloads do not provide portable progress semantics; prefer lower-layer verification where appropriate.
• Selenium API deprecations — Web Storage — local/session storage are not W3C WebDriver commands; use page-context script when storage inspection is required.
• Python exceptions — includes InvalidCookieDomainException.