> ## 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.

# Cookies

> Manage browser cookies for authentication and session handling

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

## Methods

### `page.cookies()`

Gets all cookies visible to a given URL.

```typescript theme={null}
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:**

```typescript theme={null}
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.

```typescript theme={null}
page.setCookie(...cookies: Cookie[]): Promise<void>
```

**Parameters:**

* `cookies`: One or more cookie objects to set

**Returns:** `Promise<void>`

**Example:**

```typescript theme={null}
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' }
)
```

## Cookie type

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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)
```

### Cookie-based feature flags

```typescript theme={null}
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

```typescript theme={null}
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)
```

### Debug cookie issues

```typescript theme={null}
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

```typescript theme={null}
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

<AccordionGroup>
  <Accordion title="Match domain correctly" icon="globe">
    Ensure the URL domain matches the cookie domain:

    ```typescript theme={null}
    // 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
    ```
  </Accordion>

  <Accordion title="Set secure cookies for HTTPS" icon="lock">
    Use the `secure` flag for cookies on HTTPS sites:

    ```typescript theme={null}
    await page.setCookie({
      name: 'auth_token',
      value: 'secret',
      domain: 'example.com',
      secure: true,  // Only sent over HTTPS
      httpOnly: true  // Not accessible via JavaScript
    })
    ```
  </Accordion>

  <Accordion title="Check cookie expiration" icon="calendar">
    Verify cookies haven't expired before using them:

    ```typescript theme={null}
    const sessionCookie = cookies.find(c => c.name === 'session')
    if (sessionCookie.expires && sessionCookie.expires < Date.now() / 1000) {
      console.log('Cookie expired, need to re-authenticate')
    }
    ```
  </Accordion>

  <Accordion title="Handle missing cookies" icon="question">
    Always check if cookies exist before accessing:

    ```typescript theme={null}
    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
    }
    ```
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/page/authentication">
    Handle authentication flows
  </Card>

  <Card title="Navigation" icon="compass" href="/api-reference/page/navigation">
    Navigate with cookies set
  </Card>

  <Card title="JavaScript" icon="code" href="/api-reference/page/javascript">
    Access cookies via JavaScript
  </Card>

  <Card title="Page overview" icon="window-maximize" href="/api-reference/page/overview">
    Back to Page API overview
  </Card>
</CardGroup>