From af4a1c2d26218bf371f8b2dd1e8b5546a0b86f06 Mon Sep 17 00:00:00 2001 From: Max Schmitt Date: Wed, 24 Nov 2021 21:55:03 +0100 Subject: [PATCH] docs(python): add request API examples (#10512) --- docs/src/api/class-apirequest.md | 5 +- docs/src/api/class-apirequestcontext.md | 100 ++++++++++++++++++++++ docs/src/api/class-apiresponse.md | 34 ++++++++ docs/src/test-api-testing-js.md | 2 +- packages/playwright-core/types/types.d.ts | 6 +- 5 files changed, 144 insertions(+), 3 deletions(-) diff --git a/docs/src/api/class-apirequest.md b/docs/src/api/class-apirequest.md index 2fd069de91..f2d2aef827 100644 --- a/docs/src/api/class-apirequest.md +++ b/docs/src/api/class-apirequest.md @@ -1,7 +1,10 @@ # class: APIRequest * langs: js, java, python -Exposes API that can be used for the Web API testing. +Exposes API that can be used for the Web API testing. Each Playwright browser context +has a APIRequestContext instance attached which shares cookies with the page context. +Its also possible to create a new APIRequestContext instance manually. For more information +see [here](./class-apirequestcontext). ## async method: APIRequest.newContext * langs: js, java, python diff --git a/docs/src/api/class-apirequestcontext.md b/docs/src/api/class-apirequestcontext.md index a7bc4572a8..e40c8c0284 100644 --- a/docs/src/api/class-apirequestcontext.md +++ b/docs/src/api/class-apirequestcontext.md @@ -6,6 +6,106 @@ environment or the service to your e2e test. When used on [Page] or a [BrowserCo the cookies from the corresponding [BrowserContext]. This means that if you log in using this API, your e2e test will be logged in and vice versa. +```python async +import os +import asyncio +from playwright.async_api import async_playwright, Playwright + +REPO = "test-repo-1" +USER = "github-username" +API_TOKEN = os.getenv("GITHUB_API_TOKEN") + +async def run(playwright: Playwright): + # This will launch a new browser, create a context and page. When making HTTP + # requests with the internal APIRequestContext (e.g. `context.request` or `page.request`) + # it will automatically set the cookies to the browser page and vise versa. + browser = await playwright.chromium.launch() + context = await browser.new_context(base_url="https://api.github.com") + api_request_context = context.request + page = await context.new_page() + + # Alternatively you can create a APIRequestContext manually without having a browser context attached: + # api_request_context = await playwright.request.new_context(base_url="https://api.github.com") + + # Create a repository. + response = await api_request_context.post( + "/user/repos", + headers={ + "Accept": "application/vnd.github.v3+json", + # Add GitHub personal access token. + "Authorization": f"token {API_TOKEN}", + }, + data={"name": REPO}, + ) + assert response.ok + assert response.json()["name"] == REPO + + # Delete a repository. + response = await api_request_context.delete( + f"/repos/{USER}/{REPO}", + headers={ + "Accept": "application/vnd.github.v3+json", + # Add GitHub personal access token. + "Authorization": f"token {API_TOKEN}", + }, + ) + assert response.ok + assert await response.body() == '{"status": "ok"}' + +async def main(): + async with async_playwright() as playwright: + await run(playwright) + +asyncio.run(main()) +``` + +```python sync +import os +from playwright.sync_api import sync_playwright + +REPO = "test-repo-1" +USER = "github-username" +API_TOKEN = os.getenv("GITHUB_API_TOKEN") + +with sync_playwright() as p: + # This will launch a new browser, create a context and page. When making HTTP + # requests with the internal APIRequestContext (e.g. `context.request` or `page.request`) + # it will automatically set the cookies to the browser page and vise versa. + browser = playwright.chromium.launch() + context = browser.new_context(base_url="https://api.github.com") + api_request_context = context.request + page = context.new_page() + + # Alternatively you can create a APIRequestContext manually without having a browser context attached: + # api_request_context = playwright.request.new_context(base_url="https://api.github.com") + + + # Create a repository. + response = api_request_context.post( + "/user/repos", + headers={ + "Accept": "application/vnd.github.v3+json", + # Add GitHub personal access token. + "Authorization": f"token {API_TOKEN}", + }, + data={"name": REPO}, + ) + assert response.ok + assert response.json()["name"] == REPO + + # Delete a repository. + response = api_request_context.delete( + f"/repos/{USER}/{REPO}", + headers={ + "Accept": "application/vnd.github.v3+json", + # Add GitHub personal access token. + "Authorization": f"token {API_TOKEN}", + }, + ) + assert response.ok + assert await response.body() == '{"status": "ok"}' +``` + ## async method: APIRequestContext.delete - returns: <[APIResponse]> diff --git a/docs/src/api/class-apiresponse.md b/docs/src/api/class-apiresponse.md index 5a8439a69a..2252a7b253 100644 --- a/docs/src/api/class-apiresponse.md +++ b/docs/src/api/class-apiresponse.md @@ -3,6 +3,40 @@ [APIResponse] class represents responses returned by [`method: APIRequestContext.get`] and similar methods. +```python async +import asyncio +from playwright.async_api import async_playwright, Playwright + +async def run(playwright: Playwright): + context = await playwright.request.new_context() + response = await context.get("https://example.com/user/repos") + assert response.ok + assert response.status == 200 + assert response.headers["content-type"] == "application/json; charset=utf-8" + assert response.json()["name"] == "foobar" + assert await response.body() == '{"status": "ok"}' + + +async def main(): + async with async_playwright() as playwright: + await run(playwright) + +asyncio.run(main()) +``` + +```python sync +from playwright.sync_api import sync_playwright + +with sync_playwright() as p: + context = playwright.request.new_context() + response = context.get("https://example.com/user/repos") + assert response.ok + assert response.status == 200 + assert response.headers["content-type"] == "application/json; charset=utf-8" + assert response.json()["name"] == "foobar" + assert response.body() == '{"status": "ok"}' +``` + ## async method: APIResponse.body - returns: <[Buffer]> diff --git a/docs/src/test-api-testing-js.md b/docs/src/test-api-testing-js.md index 8512118fcf..1960bdc7fe 100644 --- a/docs/src/test-api-testing-js.md +++ b/docs/src/test-api-testing-js.md @@ -163,7 +163,7 @@ const USER = 'github-username'; }); // Delete a repository. - await context.delete(`/repos/${USER}/${REPO}`{ + await context.delete(`/repos/${USER}/${REPO}`, { headers: { 'Accept': 'application/vnd.github.v3+json', // Add GitHub personal access token. diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 5f2ec34307..bd89fd5d4e 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -11813,7 +11813,9 @@ export interface AndroidWebView { } /** - * Exposes API that can be used for the Web API testing. + * Exposes API that can be used for the Web API testing. Each Playwright browser context has a APIRequestContext instance + * attached which shares cookies with the page context. Its also possible to create a new APIRequestContext instance + * manually. For more information see [here](https://playwright.dev/docs/class-apirequestcontext). */ export interface APIRequest { /** @@ -11939,6 +11941,7 @@ export interface APIRequest { * environment or the service to your e2e test. When used on [Page] or a [BrowserContext], this API will automatically use * the cookies from the corresponding [BrowserContext]. This means that if you log in using this API, your e2e test will be * logged in and vice versa. + * */ export interface APIRequestContext { /** @@ -12428,6 +12431,7 @@ export interface APIRequestContext { * [APIResponse] class represents responses returned by * [apiRequestContext.get(url[, options])](https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get) * and similar methods. + * */ export interface APIResponse { /**