From 498f9a52c633a89a4a6a89ad39f7b5a46532435e Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Fri, 8 Jan 2021 12:24:10 -0800 Subject: [PATCH] docs: update authentication guide to use storageState() api (#4948) --- docs/examples/authentication.js | 15 ++--- docs/src/auth.md | 114 ++++++++------------------------ 2 files changed, 33 insertions(+), 96 deletions(-) diff --git a/docs/examples/authentication.js b/docs/examples/authentication.js index 7001b9695c..35ab34c5a6 100644 --- a/docs/examples/authentication.js +++ b/docs/examples/authentication.js @@ -3,13 +3,13 @@ const assert = require('assert'); /** * In this script, we will login on GitHub.com through Chromium, - * and reuse the login cookies state inside WebKit. This recipe can be + * and reuse login state inside WebKit. This recipe can be * used to speed up tests by logging in once and reusing login state. * * Steps summary * 1. Login on GitHub.com in Chromium - * 2. Export cookies from Chromium browser context - * 3. Set cookies in WebKit browser context and verify login + * 2. Export storage state from Chromium browser context + * 3. Set storage state in WebKit browser context and verify login */ const account = { login: '', password: '' }; @@ -31,14 +31,13 @@ const account = { login: '', password: '' }; await crPage.click('input[type="submit"]'); await verifyIsLoggedIn(crPage); - // Get cookies from Chromium browser context - const cookies = await crContext.cookies(); + // Get storage state from Chromium browser context + const storageState = await crContext.storageState(); await crBrowser.close(); - // Create WebKit browser context and load cookies + // Create WebKit browser context with saved storage state const wkBrowser = await webkit.launch(); - const wkContext = await wkBrowser.newContext(); - await wkContext.addCookies(cookies) + const wkContext = await wkBrowser.newContext({ storageState }); // Navigate to GitHub.com and verify that we are logged in const wkPage = await wkContext.newPage(); diff --git a/docs/src/auth.md b/docs/src/auth.md index 37325af1ab..b5eb99da5b 100644 --- a/docs/src/auth.md +++ b/docs/src/auth.md @@ -69,114 +69,53 @@ existing authentication state in new browser contexts. Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) or in [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage). -The Playwright API can be used to retrieve this state from authenticated contexts -and then load it into new contexts. +Playwright provides [`method: Browser.storageState`] method that can be used to retrieve storage state from authenticated contexts and then create new contexts with prepopulated state. Cookies and local storage state can be used across different browsers. They depend on your application's authentication model: some apps might require both cookies and local storage. -The following code snippets retrieve state from an authenticated page/context and -load them into a new context. - -### Cookies +The following code snippet retrieves state from an authenticated context and +creates a new context with that state. ```js -// Get cookies and store as an env variable -const cookies = await context.cookies(); -process.env.COOKIES = JSON.stringify(cookies); +// Save storage state and store as an env variable +const storage = await context.storageState(); +process.env.STORAGE = JSON.stringify(storage); -// Set cookies in a new context -const deserializedCookies = JSON.parse(process.env.COOKIES) -await context.addCookies(deserializedCookies); +// Create a new context with the saved storage state +const storageState = JSON.parse(process.env.STORAGE); +const context = await browser.newContext({ storageState }); ``` ```python-async import json import os -# Get cookies and store as an env variable -cookies = await context.cookies() -os.environ["COOKIES"] = json.dumps(cookies) +# Save storage state and store as an env variable +storage = await context.storage_state() +os.environ["STORAGE"] = json.dumps(storage) -# Set cookies in a new context -deserialized_cookies = json.loads(os.environ["COOKIES"]) -await context.add_cookies(deserialized_cookies) +# Create a new context with the saved storage state +storage_state = json.loads(os.environ["STORAGE"]) +context = await browser.new_context(storage_state=storage_state) ``` ```python-sync import json import os -# Get cookies and store as an env variable -cookies = context.cookies() -os.environ["COOKIES"] = json.dumps(cookies) +# Save storage state and store as an env variable +storage = context.storage_state() +os.environ["STORAGE"] = json.dumps(storage) -# Set cookies in a new context -deserialized_cookies = json.loads(os.environ["COOKIES"]) -context.add_cookies(deserialized_cookies) -``` - -### Local storage -Local storage ([`window.localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)) -is specific to a particular domain. - -```js -// Get local storage and store as env variable -const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage)); -process.env.LOCAL_STORAGE = localStorage; - -// Set local storage in a new context -const localStorage = process.env.LOCAL_STORAGE; -await context.addInitScript(storage => { - if (window.location.hostname === 'example.com') { - const entries = JSON.parse(storage); - Object.keys(entries).forEach(key => { - window.localStorage.setItem(key, entries[key]); - }); - } -}, localStorage); -``` - -```python-async -import os -import json -# Get local storage and store as env variable -local_storage = await page.evaluate("() => JSON.stringify(window.localStorage)) -os.environ["LOCAL_STORAGE"] = local_storage - -# Set local storage in a new context -local_storage = os.environ["LOCAL_STORAGE"] -await context.add_init_script("""storage => { - if (window.location.hostname == 'example.com') { - entries = JSON.parse(storage) - Object.keys(entries).forEach(key => { - window.localStorage.setItem(key, entries[key]) - }) - } -}""", local_storage) -``` - -```python-sync -import os -import json -# Get local storage and store as env variable -local_storage = page.evaluate("() => JSON.stringify(window.localStorage)") -os.environ["LOCAL_STORAGE"] = local_storage - -# Set local storage in a new context -local_storage = os.environ["LOCAL_STORAGE"] -context.add_init_script("""storage => { - if (window.location.hostname == 'example.com') { - entries = JSON.parse(storage) - Object.keys(entries).forEach(key => { - window.localStorage.setItem(key, entries[key]) - }) - } -}""", local_storage) +# Create a new context with the saved storage state +storage_state = json.loads(os.environ["STORAGE"]) +context = browser.new_context(storage_state=storage_state) ``` ### Session storage + Session storage ([`window.sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)) -is specific to a particular domain. +is specific to a particular domain. Playwright does not provide API to persist session storage, but the following snippet can be used to save/load session storage. ```js // Get session storage and store as env variable @@ -247,12 +186,11 @@ on any external state. ### Example [This example script](https://github.com/microsoft/playwright/blob/master/docs/examples/authentication.js) logs in -on GitHub.com with Chromium, and then reuses the logged in cookie state in WebKit. +on GitHub.com with Chromium, and then reuses the logged in storage state in WebKit. ### API reference -- [BrowserContext] -- [`method: BrowserContext.cookies`] -- [`method: BrowserContext.addCookies`] +- [`method: BrowserContext.storageState`] +- [`method: Browser.newContext`] - [`method: Page.evaluate`] - [`method: BrowserContext.addInitScript`]