How to programmatically set up, control, and verify Google Chrome browser state using Python (Playwright CDP, SQLite, JSON configs). For setup-gen and reward-gen agents.
How to programmatically set up, control, and verify Google Chrome browser state using Python (Playwright CDP, SQLite, JSON configs). For setup-gen and reward-gen agents.
user-invocable
false
Chrome — Python Manipulation Guide
This skill teaches setup-gen (create initial browser state) and reward-gen (verify browser state after agent actions) how to work with Chrome programmatically. Unlike file-based domains, Chrome tasks involve three data layers: config files (JSON/SQLite), live browser via CDP, and accessibility tree.
import datetime
defchrome_timestamp(dt=None, seconds_ago=0):
"""Chrome timestamps: microseconds since 1601-01-01 (Windows FILETIME)."""
epoch_1601 = datetime.datetime(1601, 1, 1)
if dt isNone:
dt = datetime.datetime.utcnow() - datetime.timedelta(seconds=seconds_ago)
delta = dt - epoch_1601
returnint(delta.total_seconds() * 1_000_000)
defsetup_history(history_items):
"""history_items: list of {url, title, visit_time_from_now_in_seconds}"""# MUST close Chrome before modifying History DB
conn = sqlite3.connect(HISTORY_DB)
c = conn.cursor()
# Ensure tables exist (normally they do in an existing profile)
c.execute("""CREATE TABLE IF NOT EXISTS urls (
id INTEGER PRIMARY KEY, url TEXT, title TEXT, visit_count INTEGER DEFAULT 1,
typed_count INTEGER DEFAULT 0, last_visit_time INTEGER, hidden INTEGER DEFAULT 0
)""")
c.execute("""CREATE TABLE IF NOT EXISTS visits (
id INTEGER PRIMARY KEY, url INTEGER, visit_time INTEGER, from_visit INTEGER DEFAULT 0,
transition INTEGER DEFAULT 805306368, segment_id INTEGER DEFAULT 0,
visit_duration INTEGER DEFAULT 0
)""")
for item in history_items:
ts = chrome_timestamp(seconds_ago=item['visit_time_from_now_in_seconds'])
c.execute("INSERT INTO urls (url, title, last_visit_time) VALUES (?, ?, ?)",
(item['url'], item['title'], ts))
url_id = c.lastrowid
c.execute("INSERT INTO visits (url, visit_time) VALUES (?, ?)", (url_id, ts))
conn.commit()
conn.close()
setup_history([
{"url": "https://www.youtube.com/watch?v=abc", "title": "Video", "visit_time_from_now_in_seconds": 3600},
{"url": "https://news.example.com", "title": "News", "visit_time_from_now_in_seconds": 7200},
])
Opening Tabs via Playwright CDP
from playwright.sync_api import sync_playwright
defopen_chrome_tabs(urls, host="localhost", port=9222):
"""Open URLs in existing Chrome (must be running with --remote-debugging-port)."""with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(f"http://{host}:{port}")
context = browser.contexts[0] # use existing default profile contextfor url in urls:
page = context.new_page()
page.goto(url, timeout=60000, wait_until='networkidle')
# Close default blank tab if presentfor page in context.pages:
if page.url == "about:blank"or page.url == "chrome://newtab/":
page.close()
break# Do NOT call browser.close() — keep Chrome open for agent
open_chrome_tabs(["https://www.google.com", "https://www.github.com"])
2. Reading & Verifying Browser State (reward-gen)
Reading Preferences
prefs = read_prefs() # reuse from above# Do Not Track
do_not_track = prefs.get('enable_do_not_track', False)
# Font size
font_size = prefs.get('webkit', {}).get('webprefs', {}).get('default_font_size', 16)
# Safe browsing
safe_browsing = prefs.get('safebrowsing', {}).get('enabled', False)
enhanced_safe = prefs.get('safebrowsing', {}).get('enhanced', False)
# Color scheme
scheme = prefs.get('browser', {}).get('theme', {}).get('color_scheme2',
prefs.get('browser', {}).get('theme', {}).get('color_scheme', 0))
# 0=system, 1=light, 2=dark# Startup page
startup = prefs.get('session', {}).get('restore_on_startup', None)
# 5 or missing = open new tab page# Search engine
search = prefs.get('default_search_provider_data', {}).get('template_url_data', {}).get('short_name', '')
Reading Local State
state = read_local_state()
language = state.get('intl', {}).get('app_locale', '')
experiments = state.get('browser', {}).get('enabled_labs_experiments', [])
exp_names = [e.split("@")[0] for e in experiments]
Verifying Bookmarks
withopen(BOOKMARKS_FILE, 'r') as f:
bm = json.load(f)
bar = bm['roots']['bookmark_bar']['children']
folder_names = [b['name'] for b in bar if b['type'] == 'folder']
bookmark_urls = [b['url'] for b in bar if b['type'] == 'url']
# Check specific folder contentsdefget_folder_urls(bar_children, folder_name):
for b in bar_children:
if b['type'] == 'folder'and b['name'] == folder_name:
return [c['url'] for c in b['children'] if c['type'] == 'url']
return []
Verifying History (SQLite)
defread_history():
conn = sqlite3.connect(HISTORY_DB)
c = conn.cursor()
c.execute("SELECT url, title, last_visit_time FROM urls")
rows = c.fetchall()
conn.close()
return rows # list of (url, title, timestamp)defcheck_history_keyword_deleted(keyword):
"""True if no history URL contains the keyword."""returnall(keyword notin url for url, _, _ in read_history())
Verifying Cookies (SQLite)
defread_cookies():
conn = sqlite3.connect(COOKIES_DB)
c = conn.cursor()
c.execute("SELECT * FROM cookies")
rows = c.fetchall()
conn.close()
return rows
defcheck_cookie_domain_deleted(domain):
"""True if no cookies from this domain exist."""
cookies = read_cookies()
returnall(domain notinstr(row[1]) for row in cookies)
Verifying Extensions
defget_installed_extensions():
"""Read extension names from manifest.json files."""
names = []
ifnot os.path.isdir(EXTENSIONS_DIR):
return names
for ext_id in os.listdir(EXTENSIONS_DIR):
ext_path = os.path.join(EXTENSIONS_DIR, ext_id)
ifnot os.path.isdir(ext_path):
continuefor version in os.listdir(ext_path):
manifest = os.path.join(ext_path, version, "manifest.json")
if os.path.exists(manifest):
withopen(manifest, 'r') as f:
data = json.load(f)
names.append(data.get('name', ''))
return names
# Extension name aliases (same extension, different names across versions)
EXTENSION_ALIASES = [{"Zoom Chrome Extension", "Zoom for Google Chrome"}]
defcanonicalize_ext(name):
for group in EXTENSION_ALIASES:
if name in group:
returnsorted(group)[0]
return name
Verifying Active Tab URL via CDP
defget_active_tab_url(host="localhost", port=9222):
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(f"http://{host}:{port}")
context = browser.contexts[0]
# Last page is usually the active oneif context.pages:
page = context.pages[-1]
return page.url
returnNone
Verifying Page Content via CDP
defget_page_info(url, host="localhost", port=9222):
"""Navigate to URL and return {title, url, content}."""with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(f"http://{host}:{port}")
context = browser.contexts[0]
page = context.new_page()
page.goto(url, timeout=60000, wait_until='networkidle')
return {"title": page.title(), "url": page.url, "content": page.content()}
defget_all_open_tabs(host="localhost", port=9222):
"""Return list of {title, url} for all open tabs."""with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(f"http://{host}:{port}")
tabs = []
for ctx in browser.contexts:
for page in ctx.pages:
try:
page.wait_for_load_state('networkidle', timeout=30000)
tabs.append({"title": page.title(), "url": page.url})
except:
tabs.append({"title": "", "url": page.url})
return tabs
defcheck_desktop_shortcut(expected_name):
"""Check if a .desktop shortcut exists on Desktop."""
desktop_dir = os.path.expanduser("~/Desktop")
for fname in os.listdir(desktop_dir):
if fname.endswith('.desktop'):
withopen(os.path.join(desktop_dir, fname), 'r') as f:
content = f.read()
for line in content.split('\n'):
if line.startswith('Name='):
actual = line[5:]
if expected_name.lower() in actual.lower() or actual.lower() in expected_name.lower():
returnTruereturnFalse
3. Bitter Lessons
Chrome must be killed before modifying SQLite databases. History, Cookies, and other SQLite files are locked while Chrome is running. Setup scripts must pkill chrome, modify files, then relaunch with --remote-debugging-port=1337. Forgetting this causes "database is locked" errors.
Chrome timestamps are NOT Unix timestamps. Chrome uses microseconds since 1601-01-01 (Windows FILETIME epoch). datetime(1601,1,1) + timedelta(microseconds=chrome_ts) gives the real time. Writing Unix timestamps will produce dates in the 1600s.
connect_over_cdp reuses existing contexts.browser.contexts[0] is the real Chrome profile with cookies, history, and extensions. Do NOT create browser.new_context() — it creates an incognito-like context that shares nothing with the user's profile.
URL comparison must normalize aggressively.www.google.com and google.com are the same. airbnb.com and airbnb.com.sg may be the same. Always strip www, ignore TLD suffix, and normalize trailing slashes before comparing.
Preferences file has async writes. Chrome may not flush settings to Preferences immediately. After changing settings via the Chrome UI, poll the file up to 5 times with 1-second delays. Similarly, after writing Preferences, Chrome may overwrite your changes on next save. Write BEFORE Chrome starts.
Accessibility tree URL lacks protocol. The URL from AT-SPI's "Address and search bar" entry has no https:// prefix. Always prepend a goto_prefix (typically "https://") before using it.
Extension names have aliases. The same Chrome extension can have different manifest.json names across versions (e.g., "Zoom Chrome Extension" vs "Zoom for Google Chrome"). Canonicalize names before comparison using alias groups.
page.goto() with networkidle can hang on streaming pages. Some pages (YouTube live, infinite feeds) never reach networkidle. Use timeout=60000 and catch TimeoutError gracefully — the page may still be usable.
socat bridges port 9222 to 1337 inside the VM. Chrome runs with --remote-debugging-port=1337 internally. An socat tcp-listen:9222,fork tcp:localhost:1337 bridge exposes it on port 9222 for external access. Setup scripts must launch both processes.
ARM machines use chromium, x86 uses google-chrome. Binary name, user data path, and accessibility tree application name all differ. Check platform.machine() to determine which binary to use. ARM: ~/snap/chromium/common/chromium/Default/, x86: ~/.config/google-chrome/Default/.
HTML parsing needs shadow DOM traversal for Chrome settings. Chrome settings pages (chrome://settings/*) use nested shadow DOMs. Regular CSS selectors don't penetrate shadow roots. Use page.evaluate() with JavaScript that calls .shadowRoot.querySelector() chains.
compare_urls drops TLD suffixes entirely. The URL normalizer uses tldextract and ignores the suffix, so airbnb.com and airbnb.co.uk normalize to the same domain. This is intentional for cross-region tolerance but can cause false matches.
Cookie values are encrypted on disk. Chrome encrypts cookie values using platform-specific keys (DPAPI on Windows, keychain on macOS, gnome-keyring on Linux). The cookies table has encrypted value and encrypted_value columns. For verification, check domain/name presence rather than decrypting values.
Post-config must kill and restart Chrome before reading settings. Many evaluators use a postconfig sequence: pkill chrome → sleep 3s → relaunch Chrome → sleep 3s → then read. This ensures settings are flushed to disk and Chrome re-reads the state cleanly.
