Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uplink.build/llms.txt

Use this file to discover all available pages before exploring further.

Read and write browser cookies to manage authentication, sessions, and user preferences.

​
Methods

​
page.cookies()

Gets all cookies visible to a given URL. 
page.cookies(url: string): Promise<Cookie[]>
Parameters:
  • url: URL to get cookies for (cookies are domain-scoped)
Returns: Promise<Cookie[]> - Array of cookie objects Example: 
const cookies = await page.cookies('https://example.com')

console.log(`Found ${cookies.length} cookies`)
cookies.forEach(cookie => {
  console.log(`${cookie.name}: ${cookie.value}`)
})

​
page.setCookie()

Sets one or more cookies. 
page.setCookie(...cookies: Cookie[]): Promise<void>
Parameters:
  • cookies: One or more cookie objects to set
Returns: Promise<void> Example: 
await page.setCookie({
  name: 'session',
  value: 'abc123xyz',
  domain: 'example.com',
  path: '/',
  secure: true,
  httpOnly: true
})

// Set multiple cookies
await page.setCookie(
  { name: 'user_id', value: '12345', domain: 'example.com' },
  { name: 'theme', value: 'dark', domain: 'example.com' }
)

interface Cookie {
  name: string           // Cookie name
  value: string          // Cookie value
  domain?: string        // Domain (e.g., "example.com")
  path?: string          // Path (e.g., "/")
  expires?: number       // Expiration timestamp (Unix time)
  size?: number          // Cookie size in bytes
  httpOnly?: boolean     // HTTP-only flag
  secure?: boolean       // Secure flag (HTTPS only)
}

​
Complete examples

​
Check authentication status

async function isLoggedIn(page) {
  const cookies = await page.cookies('https://example.com')
  const sessionCookie = cookies.find(c => c.name === 'session_token')

  if (!sessionCookie) {
    return false
  }

  // Check if cookie is expired
  if (sessionCookie.expires && sessionCookie.expires < Date.now() / 1000) {
    console.log('Session cookie expired')
    return false
  }

  return true
}

await page.goto('https://example.com')
const authenticated = await isLoggedIn(page)
console.log('Authenticated:', authenticated)

​
Transfer session between browsers

// Get cookies from first browser
const browser1 = await client.launch()
const page1 = await browser1.newPage()

await page1.goto('https://example.com/login')
// ... perform login ...

const cookies = await page1.cookies('https://example.com')
console.log('Captured session cookies')

// Transfer to second browser
const browser2 = await client.launch()
const page2 = await browser2.newPage()

await page2.setCookie(...cookies)
await page2.goto('https://example.com/dashboard')

// page2 is now logged in with the same session
console.log('Session transferred to second browser')

​
Inject authentication cookies

async function loginWithCookies(page, authToken) {
  // Set authentication cookie before navigating
  await page.setCookie({
    name: 'auth_token',
    value: authToken,
    domain: 'example.com',
    path: '/',
    secure: true,
    httpOnly: true,
    expires: Math.floor(Date.now() / 1000) + 86400  // 24 hours
  })

  // Navigate - now authenticated
  await page.goto('https://example.com/dashboard')

  // Verify authentication worked
  const pageTitle = await page.evaluate(() => document.title)
  console.log('Logged in, page title:', pageTitle)
}

await loginWithCookies(page, 'my-auth-token-xyz')

​
Save and restore session

import fs from 'fs/promises'

// Save session
async function saveSession(page, filename) {
  const cookies = await page.cookies('https://example.com')
  await fs.writeFile(filename, JSON.stringify(cookies, null, 2))
  console.log('Session saved to', filename)
}

// Restore session
async function restoreSession(page, filename) {
  const cookiesJson = await fs.readFile(filename, 'utf-8')
  const cookies = JSON.parse(cookiesJson)

  await page.setCookie(...cookies)
  console.log('Session restored from', filename)
}

// Usage
await page.goto('https://example.com/login')
// ... perform login ...
await saveSession(page, 'session.json')

// Later, in a new session
await restoreSession(page, 'session.json')
await page.goto('https://example.com/dashboard')

​
Clear cookies

async function clearCookies(page, domain) {
  const cookies = await page.cookies(`https://${domain}`)

  // Delete each cookie by setting expired date
  const expiredCookies = cookies.map(cookie => ({
    ...cookie,
    expires: 0  // Expire immediately
  }))

  await page.setCookie(...expiredCookies)
  console.log(`Cleared ${cookies.length} cookies for ${domain}`)
}

await clearCookies(page, 'example.com')

// Verify cookies are cleared
const remaining = await page.cookies('https://example.com')
console.log('Remaining cookies:', remaining.length)

async function enableFeature(page, featureName) {
  await page.setCookie({
    name: `feature_${featureName}`,
    value: 'enabled',
    domain: 'example.com',
    path: '/'
  })

  console.log(`Feature "${featureName}" enabled`)
}

async function isFeatureEnabled(page, featureName) {
  const cookies = await page.cookies('https://example.com')
  const featureCookie = cookies.find(c => c.name === `feature_${featureName}`)

  return featureCookie?.value === 'enabled'
}

// Enable dark mode
await enableFeature(page, 'dark_mode')

// Check if enabled
const darkModeEnabled = await isFeatureEnabled(page, 'dark_mode')
console.log('Dark mode:', darkModeEnabled ? 'ON' : 'OFF')

​
Manage user preferences

async function setUserPreferences(page, prefs) {
  await page.setCookie({
    name: 'user_prefs',
    value: JSON.stringify(prefs),
    domain: 'example.com',
    path: '/',
    expires: Math.floor(Date.now() / 1000) + (365 * 86400)  // 1 year
  })
}

async function getUserPreferences(page) {
  const cookies = await page.cookies('https://example.com')
  const prefsCookie = cookies.find(c => c.name === 'user_prefs')

  if (prefsCookie) {
    return JSON.parse(prefsCookie.value)
  }

  return null
}

// Set preferences
await setUserPreferences(page, {
  theme: 'dark',
  language: 'en',
  notifications: true
})

// Read preferences
const prefs = await getUserPreferences(page)
console.log('User preferences:', prefs)

async function debugCookies(page, url) {
  const cookies = await page.cookies(url)

  console.log(`\n=== Cookies for ${url} ===`)
  console.log(`Total cookies: ${cookies.length}\n`)

  cookies.forEach(cookie => {
    console.log(`Name: ${cookie.name}`)
    console.log(`Value: ${cookie.value}`)
    console.log(`Domain: ${cookie.domain}`)
    console.log(`Path: ${cookie.path}`)
    console.log(`Secure: ${cookie.secure}`)
    console.log(`HttpOnly: ${cookie.httpOnly}`)

    if (cookie.expires) {
      const expiryDate = new Date(cookie.expires * 1000)
      const isExpired = expiryDate < new Date()
      console.log(`Expires: ${expiryDate.toISOString()} ${isExpired ? '(EXPIRED)' : ''}`)
    } else {
      console.log('Expires: Session')
    }

    console.log('---')
  })
}

await page.goto('https://example.com')
await debugCookies(page, 'https://example.com')

​
A/B testing with cookies

async function assignABTestVariant(page) {
  const variant = Math.random() < 0.5 ? 'A' : 'B'

  await page.setCookie({
    name: 'ab_test_variant',
    value: variant,
    domain: 'example.com',
    path: '/',
    expires: Math.floor(Date.now() / 1000) + (30 * 86400)  // 30 days
  })

  console.log('Assigned A/B test variant:', variant)
  return variant
}

async function getABTestVariant(page) {
  const cookies = await page.cookies('https://example.com')
  const variantCookie = cookies.find(c => c.name === 'ab_test_variant')

  return variantCookie?.value || null
}

// Assign variant if not already assigned
let variant = await getABTestVariant(page)
if (!variant) {
  variant = await assignABTestVariant(page)
}

await page.goto('https://example.com')
console.log('Testing with variant:', variant)

​
Best practices

Ensure the URL domain matches the cookie domain:
// Cookie domain: example.com
const cookies = await page.cookies('https://example.com')  // ✓ Correct

const cookies = await page.cookies('https://other.com')    // ✗ Won't find it
Use the secure flag for cookies on HTTPS sites:
await page.setCookie({
  name: 'auth_token',
  value: 'secret',
  domain: 'example.com',
  secure: true,  // Only sent over HTTPS
  httpOnly: true  // Not accessible via JavaScript
})
Always check if cookies exist before accessing:
const cookies = await page.cookies('https://example.com')
const authCookie = cookies.find(c => c.name === 'auth')

if (!authCookie) {
  console.log('Not authenticated')
  // Handle unauthenticated state
}

Authentication

Handle authentication flows

Navigation

Navigate with cookies set

JavaScript

Access cookies via JavaScript

Page overview

Back to Page API overview