Filip/playwright
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs: Emulation improvements (#17090)

Browse source
This commit is contained in:
Debbie O'Brien 2022-09-08 18:57:20 +02:00 committed by GitHub
parent f7c474bc0f
commit 1f34531a22
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 357 additions and 226 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

453
docs/src/emulation.md
View file

@ -3,37 +3,69 @@ id: emulation
title: "Emulation"
---
Playwright allows overriding various parameters of the device where the browser is running:
- viewport size, device scale factor, touch support
- locale, timezone
- color scheme
- geolocation
Most of these parameters are configured during the browser context construction, but some of them such as viewport size
can be changed for individual pages.
<!-- TOC -->
## Playwright Test vs. Library
* langs: js
:::caution
This guide is for [Playwright Library](./library.md), if you are using Playwright Test (`@playwright/test`) see [here](./test-configuration.md).
:::
With Playwright you can test your app on any browser as well as emulate a real device such as a mobile phone or tablet. Simply configure the devices you would like to emulate and Playwright will simulate the browser behavior such as `"userAgent"`, `"screenSize"`, `"viewport"` and if it `"hasTouch"` enabled. You can also emulate the `"geolocation"`, `"locale"` and `"timezone"` for all tests or for a specific test as well as set the `"permissions"` to show notifications or change the `"colorScheme"`.
## Devices
* langs: js, python, csharp
* langs: js, csharp, python
Playwright comes with a registry of device parameters for selected mobile devices. It can be used to simulate browser
behavior on a mobile device:
Playwright comes with a [registry of device parameters](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json) using [`property: Playwright.devices`] for selected desktop, tablet and mobile devices. It can be used to simulate browser behavior for a specific device such as user agent, screen size, viewport and if it has touch enabled. All tests will run with the specified device parameters.
```js
```js tab=js-ts
// playwright.config.ts
import { type PlaywrightTestConfig, devices } from '@playwright/test'; // import devices
const config: PlaywrightTestConfig = {
projects: [
{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
},
},
{
name: 'Mobile Safari',
use: {
...devices['iPhone 12'],
},
},
],
};
export default config;
```
```js tab=js-js
// playwright.config.js
// @ts-check
const { devices } = require('@playwright/test'); // require devices
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
projects: [
{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
},
},
{
name: 'Mobile Safari',
use: {
...devices['iPhone 12'],
},
},
],
};
module.exports = config;
```
```js tab=js-library
const { chromium, devices } = require('playwright');
const browser = await chromium.launch();
const pixel2 = devices['Pixel 2'];
const iphone12 = devices['iPhone 12'];
const context = await browser.newContext({
...pixel2,
...iphone12,
});
```
@ -42,10 +74,10 @@ import asyncio
from playwright.async_api import async_playwright
async def run(playwright):
pixel_2 = playwright.devices['Pixel 2']
iphone_12 = playwright.devices['iPhone 12']
browser = await playwright.webkit.launch(headless=False)
context = await browser.new_context(
**pixel_2,
**iphone_12,
)
async def main():
@ -58,10 +90,10 @@ asyncio.run(main())
from playwright.sync_api import sync_playwright
def run(playwright):
pixel_2 = playwright.devices['Pixel 2']
iphone_12 = playwright.devices['iPhone 12']
browser = playwright.webkit.launch(headless=False)
context = browser.new_context(
**pixel_2,
**iphone_12,
)
with sync_playwright() as playwright:
@ -81,61 +113,43 @@ class Program
{
Headless: False
});
var pixel2 = playwright.Devices["Pixel 2"];
await using var context = await browser.NewContextAsync(pixel2);
var iphone12 = playwright.Devices["iPhone 12"];
await using var context = await browser.NewContextAsync(iphone12);
}
}
```
All pages created in the context above will share the same device parameters.
## Viewport
### API reference
- [`property: Playwright.devices`]
- [`method: Browser.newContext`]
The viewport is included in the device but you can override it for some tests with [`method: Page.setViewportSize`].
<br/>
```js tab=js-ts
import { test, expect } from '@playwright/test';
## User agent
// Run tests in this file with portrait-like viewport.
test.use({
viewport: { width: 600, height: 900 },
});
All pages created in the context above will share the user agent specified:
```js
const context = await browser.newContext({
userAgent: 'My user agent'
test('my portrait test', async ({ page }) => {
// ...
});
```
```java
BrowserContext context = browser.newContext(new Browser.NewContextOptions()
.setUserAgent("My user agent"));
```js tab=js-js
const { test, expect } = require('@playwright/test');
// Run tests in this file with portrait-like viewport.
test.use({
viewport: { width: 600, height: 900 },
});
test('my portrait test', async ({ page }) => {
// ...
});
```
```python async
context = await browser.new_context(
user_agent='My user agent'
)
```
```python sync
context = browser.new_context(
user_agent='My user agent'
)
```
```csharp
var context = await browser.NewContextAsync(new BrowserNewContextOptions { UserAgent = "My User Agent" });
```
### API reference
- [`method: Browser.newContext`]
<br/>
## Viewport
Create a context with custom viewport size:
```js
```js tab=js-library
// Create context with given viewport
const context = await browser.newContext({
viewport: { width: 1280, height: 1024 }
@ -150,6 +164,33 @@ const context = await browser.newContext({
deviceScaleFactor: 2,
});
```
The same works inside a describe block.
```js tab=js-ts
import { test, expect } from '@playwright/test';
test.describe('locale block', () => {
// Run tests in this describe block with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } });
test('my portrait test', async ({ page }) => {
// ...
});
});
```
```js tab=js-js
const { test, expect } = require('@playwright/test');
test.describe('locale block', () => {
// Run tests in this describe block with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } });
test('my portrait test', async ({ page }) => {
// ...
});
});
```
```java
// Create context with given viewport
@ -213,16 +254,37 @@ await using var context = await browser.NewContextAsync(new()
DeviceScaleFactor = 2
});
```
## Locale & Timezone
### API reference
- [`method: Browser.newContext`]
- [`method: Page.setViewportSize`]
Emulate the user Locale and Timezone which can be set globally for all tests in the config and then overridden for particular tests.
<br/>
```js tab=js-ts
import { test, expect } from '@playwright/test';
## Locale & timezone
test.use({
locale: 'de-DE',
timezoneId: 'Europe/Berlin',
});
```js
test('my test for de lang in Berlin timezone', async ({ page }) => {
// ...
});
```
```js tab=js-js
const { test, expect } = require('@playwright/test');
test.use({
locale: 'de-DE',
timezoneId: 'Europe/Berlin',
});
test('my test for de lang in Berlin timezone', async ({ page }) => {
// ...
});
```
```js tab=js-library
// Emulate locale and time
const context = await browser.newContext({
locale: 'de-DE',
@ -260,17 +322,34 @@ await using var context = await browser.NewContextAsync(new()
TimezoneId = "Europe/Berlin"
});
```
### API reference
- [`method: Browser.newContext`]
<br/>
## Permissions
Allow all pages in the context to show system notifications:
Allow app to show system notifications.
```js
```js tab=js-js
// @ts-check
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
use: {
permissions: ['notifications'],
},
};
module.exports = config;
```
```js tab=js-ts
import type { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
use: {
permissions: ['notifications'],
},
};
export default config;
```
```js tab=js-library
const context = await browser.newContext({
permissions: ['notifications'],
});
@ -293,9 +372,32 @@ context = browser.new_context(
)
```
Grant all pages in the existing context access to current location:
Allow test to request current location.
```js
```js tab=js-js
// @ts-check
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
use: {
permissions: ['geolocation'],
},
};
module.exports = config;
```
```js tab=js-ts
import type { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
use: {
permissions: ['geolocation'],
},
};
export default config;
```
```js tab=js-library
await context.grantPermissions(['geolocation']);
```
@ -315,9 +417,32 @@ context.grant_permissions(['geolocation'])
await context.GrantPermissionsAsync(new[] { "geolocation" });
```
Grant notifications access from a specific domain:
Allow notifications for a specific domain.
```js
```js tab=js-js
// @ts-check
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
use: {
permissions: ['notifications'], {origin: 'https://skype.com'},
},
};
module.exports = config;
```
```js tab=js-ts
import type { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
use: {
permissions: ['notifications'], {origin: 'https://skype.com'},
},
};
export default config;
```
```js tab=js-library
await context.grantPermissions(['notifications'], {origin: 'https://skype.com'} );
```
@ -338,9 +463,10 @@ context.grant_permissions(['notifications'], origin='https://skype.com')
await context.GrantPermissionsAsync(new[] { "notifications" }, origin: "https://skype.com");
```
Revoke all permissions:
Revoke all permissions with [`method: BrowserContext.clearPermissions`].
```js
// Library
await context.clearPermissions();
```
@ -359,23 +485,42 @@ context.clear_permissions()
```csharp
await context.ClearPermissionsAsync();
```
### API reference
- [`method: Browser.newContext`]
- [`method: BrowserContext.grantPermissions`]
- [`method: BrowserContext.clearPermissions`]
<br/>
## Geolocation
Create a context with `"geolocation"` permissions granted:
Create a test with `"geolocation"` permissions granted and geolocation set to a specific area.
```js
```js tab=js-ts
import { test, expect } from '@playwright/test';
test.use({
geolocation: { longitude: 48.858455, latitude: 2.294474 },
permissions: ['geolocation'],
});
test('my test with geolocation', async ({ page }) => {
// ...
});
```
```js tab=js-js
const { test, expect } = require('@playwright/test');
test.use({
geolocation: { longitude: 48.858455, latitude: 2.294474 },
permissions: ['geolocation'],
});
test('my test with geolocation', async ({ page }) => {
// ...
});
```
```js tab=js-library
const context = await browser.newContext({
geolocation: { longitude: 48.858455, latitude: 2.294474 },
permissions: ['geolocation']
});
```
```java
@ -429,18 +574,35 @@ await context.SetGeolocationAsync(new Geolocation() { Longitude = 48.858455f, La
```
**Note** you can only change geolocation for all pages in the context.
## Color Scheme and Media
### API reference
- [`method: Browser.newContext`]
- [`method: BrowserContext.setGeolocation`]
Create a test that emulates the users `"colorScheme"`. Supported values are 'light', 'dark', 'no-preference'. You can also emulate the media type with [`method: Page.emulateMedia`].
<br/>
```js tab=js-ts
import { test, expect } from '@playwright/test';
## Color scheme and media
test.use({
colorScheme: 'dark' // or 'light'
});
Create a context with dark or light mode. Pages created in this context will follow this color scheme preference.
test('my test with dark mode', async ({ page }) => {
// ...
});
```
```js
```js tab=js-js
const { test, expect } = require('@playwright/test');
test.use({
colorScheme: 'dark' // or 'light'
});
test('my test with dark mode', async ({ page }) => {
// ...
});
```
```js tab=js-library
// Create context with dark mode
const context = await browser.newContext({
colorScheme: 'dark' // or 'light'
@ -535,7 +697,82 @@ await page.EmulateMediaAsync(new()
Media = Media.Print
});
```
## User Agent
### API reference
- [`method: Browser.newContext`]
- [`method: Page.emulateMedia`]
The User Agent is included in the device and therefore you will rarely need to change it however if you do need to test a different user agent you can override it with the `userAgent` property.
```js tab=js-ts
import { test, expect } from '@playwright/test';
test.use({ userAgent: 'My user agent'});
test('my user agent test', async ({ page }) => {
// ...
});
```
```js tab=js-js
const { test, expect } = require('@playwright/test');
test.use({ userAgent: 'My user agent' });
test('my user agent test', async ({ page }) => {
// ...
});
```
```js tab=js-library
const context = await browser.newContext({
userAgent: 'My user agent'
});
```
```java
BrowserContext context = browser.newContext(new Browser.NewContextOptions()
.setUserAgent("My user agent"));
```
```python async
context = await browser.new_context(
user_agent='My user agent'
)
```
```python sync
context = browser.new_context(
user_agent='My user agent'
)
```
```csharp
var context = await browser.NewContextAsync(new BrowserNewContextOptions { UserAgent = "My User Agent" });
```
## JavaScript Enabled
Emulate a user scenario where JavaScript is disabled.
```js tab=js-ts
import { test, expect } from '@playwright/test';
test.use({ javaScriptEnabled: false });
test('test with no JavaScript', async ({ page }) => {
// ...
});
```
```js tab=js-js
const { test, expect } = require('@playwright/test');
test.use({ javaScriptEnabled: false });
test('test with no JavaScript', async ({ page }) => {
// ...
});
```
```js tab=js-library
const context = await browser.newContext({
javaScriptEnabled: false
});
```

130
docs/src/test-configuration-js.md
View file

@ -5,7 +5,7 @@ title: "Configuration"
Playwright Test provides options to configure the default `browser`, `context` and `page` fixtures. For example there are options for `headless`, `viewport` and `ignoreHTTPSErrors`. You can also record a video or a trace for the test or capture a screenshot at the end.
Finally, there are plenty of testing options like `timeout` or `testDir` that configure how your tests are collected and executed.
There are plenty of testing options like `timeout` or `testDir` that configure how your tests are collected and executed.
You can specify any options globally in the configuration file, and most of them locally in a test file.
@ -13,7 +13,7 @@ See the full list of [test options][TestOptions] and all [configuration properti
## Global configuration
Create `playwright.config.js` (or `playwright.config.ts`) and specify options in the [`property: TestConfig.use`] section.
Create a `playwright.config.js` (or `playwright.config.ts`) and specify options in the [`property: TestConfig.use`] section.
```js tab=js-js
// @ts-check
@ -47,7 +47,7 @@ export default config;
Now run tests as usual, Playwright Test will pick up the configuration file automatically.
```bash
npx playwright test --browser=firefox
npx playwright test
```
If you put your configuration file in a different place, pass it with `--config` option.
@ -58,15 +58,13 @@ npx playwright test --config=tests/my.config.js
## Local configuration
With [`method: Test.use`] you can override some options for a file or a [`method: Test.describe#1`] block.
You can override some options for a file or describe block.
```js tab=js-js
// example.spec.js
const { test, expect } = require('@playwright/test');
// Run tests in this file with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } });
test('my portrait test', async ({ page }) => {
// ...
});
@ -75,10 +73,8 @@ test('my portrait test', async ({ page }) => {
```js tab=js-ts
// example.spec.ts
import { test, expect } from '@playwright/test';
// Run tests in this file with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } });
test('my portrait test', async ({ page }) => {
// ...
});
@ -89,11 +85,9 @@ The same works inside describe.
```js tab=js-js
// example.spec.js
const { test, expect } = require('@playwright/test');
test.describe('locale block', () => {
// Run tests in this describe block with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } });
test('my portrait test', async ({ page }) => {
// ...
});
@ -103,11 +97,9 @@ test.describe('locale block', () => {
```js tab=js-ts
// example.spec.ts
import { test, expect } from '@playwright/test';
test.describe('locale block', () => {
// Run tests in this describe block with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } });
test('my portrait test', async ({ page }) => {
// ...
});
@ -116,7 +108,9 @@ test.describe('locale block', () => {
## Basic options
These are commonly used options for various scenarios. You usually set them globally in [configuration file](#global-configuration).
Normally you would start with emulating a device, for example Desktop Chromium. See our [Emulation](./emulation.md) guide to learn more.
Here are some of the commonly used options for various scenarios. You usually set them globally in the [configuration file](#global-configuration).
- `actionTimeout` - Timeout for each Playwright action in milliseconds. Defaults to `0` (no timeout). Learn more about [various timeouts](./test-timeouts.md).
- `baseURL` - Base URL used for all pages in the context. Allows navigating by using just the path, for example `page.goto('/settings')`.
@ -126,6 +120,11 @@ These are commonly used options for various scenarios. You usually set them glob
- `headless` - Whether to run the browser in headless mode.
- `viewport` - Viewport used for all pages in the context.
- `storageState` - Populates context with given storage state. Useful for easy authentication, [learn more](./auth.md).
- `colorScheme` - Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`.
- `geolocation` - Context geolocation.
- `locale` - [Emulates](./emulation.md) the user locale, for example `en-GB`, `de-DE`, etc.
- `permissions` - A list of permissions to grant to all pages in the context.
- `timezoneId` - Changes the timezone of the context.
```js tab=js-js
// @ts-check
@ -231,111 +230,6 @@ Running 1 test using 1 worker
✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
```
## Emulation
Playwright can [emulate different environments](./emulation.md) like mobile device, locale or timezone.
Here is an example configuration that runs tests in "Pixel 4" and "iPhone 11" emulation modes. Note that it uses the [projects](./test-advanced.md#projects) feature to run the same set of tests in multiple configurations.
```js tab=js-js
// playwright.config.js
// @ts-check
const { devices } = require('@playwright/test');
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
projects: [
// "Pixel 4" tests use Chromium browser.
{
name: 'Pixel 4',
use: {
browserName: 'chromium',
...devices['Pixel 4'],
},
},
// "iPhone 11" tests use WebKit browser.
{
name: 'iPhone 11',
use: {
browserName: 'webkit',
...devices['iPhone 11'],
},
},
],
};
module.exports = config;
```
```js tab=js-ts
// playwright.config.ts
import { type PlaywrightTestConfig, devices } from '@playwright/test';
const config: PlaywrightTestConfig = {
projects: [
// "Pixel 4" tests use Chromium browser.
{
name: 'Pixel 4',
use: {
browserName: 'chromium',
...devices['Pixel 4'],
},
},
// "iPhone 11" tests use WebKit browser.
{
name: 'iPhone 11',
use: {
browserName: 'webkit',
...devices['iPhone 11'],
},
},
],
};
export default config;
```
You can specify options separately instead of using predefined devices. There are also more options such as locale, geolocation, and timezone which can be configured.
- `colorScheme` - Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`.
- `deviceScaleFactor` - Specify device scale factor (can be thought of as dpr). Defaults to `1`.
- `geolocation` - Context geolocation.
- `hasTouch` - Specifies if device supports touch events.
- `isMobile` - Whether the `meta viewport` tag is taken into account and touch events are enabled.
- `javaScriptEnabled` - Whether or not to enable JavaScript in the context.
- `locale` - User locale, for example `en-GB`, `de-DE`, etc.
- `permissions` - A list of permissions to grant to all pages in the context.
- `timezoneId` - Changes the timezone of the context.
- `userAgent` - Specific user agent to use in the context.
```js tab=js-js
// @ts-check
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
use: {
locale: 'fr-FR',
geolocation: { longitude: 48.858455, latitude: 2.294474 },
permissions: ['geolocation'],
},
};
module.exports = config;
```
```js tab=js-ts
import type { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
use: {
locale: 'fr-FR',
geolocation: { longitude: 48.858455, latitude: 2.294474 },
permissions: ['geolocation'],
},
};
export default config;
```
## Network
Available options to configure networking: