Browsers
Precept.Web drives a browser through Playwright. The package carries Playwright's driver but not
the browsers themselves, so they have to be on the machine. By default, a launch that finds no
browser installs the one it needs and launches again:
{
"Web": { "InstallBrowsers": "Auto" }
}
| Value | What it does |
|---|---|
Auto (default) |
Installs the browser after a launch has failed, once per run. A new machine and a fresh agent image both run a web test without a separate step. It costs nothing on a machine that already has the browser. The download is logged to the test rather than the console. |
Never |
Fails the launch, in Playwright's own words. Use it on an air-gapped agent, or in an image that was supposed to bake the browsers in, so a missing browser is reported rather than fixed. |
Always |
Installs before launching, every time. It costs a driver round trip per run to confirm what is usually already there. |
To install by hand, under Never or to warm an image before the suite runs:
pwsh Checkout.Web.Tests/bin/Debug/net10.0/playwright.ps1 install chromium
Without PowerShell, invoke the bundled driver directly:
Checkout.Web.Tests/bin/Debug/net10.0/.playwright/node/darwin-arm64/node Checkout.Web.Tests/bin/Debug/net10.0/.playwright/package/cli.js install chromium
Which browser#
{
"Web": { "Browser": "chromium" }
}
chromium, firefox and webkit are Playwright's own builds, downloaded into its cache. chrome
and edge are the browsers the machine has installed, driven through Chromium. That is what
"does it work in real Edge" asks, and Playwright's bundled Chromium cannot answer it. Their
pre-release channels are named the way the vendors name them: chrome-beta, chrome-dev,
chrome-canary, edge-beta, edge-dev, edge-canary. safari is accepted as a name for WebKit.
A channel can also be set on its own, which is how a pipeline moves an otherwise unchanged suite onto the agent's browser:
{
"Web": { "Browser": "chromium", "Channel": "msedge" }
}
Channel wins when both are given. A value that is neither an engine nor a channel fails the run
with a message about Web:Browser, rather than reaching Playwright, whose failure would name a
browser you cannot find in your settings file.
InstallBrowsers covers the engines only. Installing an engine fills Playwright's own cache, but
installing a channel runs the vendor's installer against the machine, which is more than an
unattended recovery should do. A missing Chrome or Edge therefore fails with the path Playwright
looked in. Install it with Always, or with a line in the image build.
Emulating a device#
{
"Web": { "Device": "iPhone 15" }
}
The names are Playwright's own (iPhone 15, Pixel 7, iPad Mini landscape, Desktop Safari)
and are matched however they were typed. One name sets the viewport, the user agent, the device
scale factor and the touch and mobile flags together. That combination is what makes a page serve
its mobile layout rather than a narrow desktop one.
Emulation decides what the page is told about itself, not which engine renders it. A device
Playwright associates with WebKit is still driven by whatever Browser says. Name webkit as well
when the engine is the point. A device that is not in the registry fails the run with a message
about Web:Device.
More than one user in a scenario#
Browser.StartAsync() starts the test's own session. Pass a name to open another one beside it, in
the same browser but sharing nothing else: its own context, its own cookies, its own storage:
var alice = await Browser.StartAsync("alice");
var bob = await Browser.StartAsync("bob");
await alice.Page.GetByRole(AriaRole.Button, new() { Name = "Share" }).ClickAsync();
await Assert.That(bob.Page.GetByText("Alice shared a document")).ToBeVisibleAsync();
While the dashboard is open, you can watch any running Chromium session live, headless ones included.
Every member of Browser takes the name, so Browser.PageAsync("bob") and
Browser.GoToAsync("/inbox", "bob") reach the same session. Asking for a name twice in one test
returns the session that name already has. Each session is disposed with the test, and each files
its artifacts under its own name, failure-alice.png and trace-bob.zip, so two users failing in
one scenario do not overwrite each other's evidence.
Page objects for two users#
Page objects read IPageContext.Page on every use, and that property is assignable. Acting as
another user means pointing the context at their page:
context.Page = (await Browser.StartAsync("bob")).Page;
await signIn.SignInAsync("bob", password); // every page object is now Bob's
context.Page = alice.Page; // and back again
There is one context per test, and every page object follows it together, which is what keeps this to one assignment rather than a second set of objects. The cost is that the context points at one page at a time, so three things are the suite's own to handle:
- Two users acting at the same moment, such as a wait armed on Bob's page while Alice clicks,
needs Bob's
IPagedirectly. One property cannot be two pages. - A page object holding state holds it for the test, not for a user. Two users sharing one instance share whatever it remembers.
- Restoring after a failure. An assertion that throws between the two assignments leaves the
context on the wrong user for the rest of the scenario, including its
[AfterTest]hook. Put the restore in afinally, or a Reqnroll[AfterScenario], where it matters.
A suite where the first cost bites often can give each user an actor instead of sharing one context. See Screenplay, which drives these same named sessions.
A test that starts only named sessions has no default session for the injected context to fall back to. The error says so by name, rather than claiming the test never opened a browser:
No browser session has been started for this test. … This test has started 'alice' and 'bob',
which the injected context does not follow until it is pointed at one:
context.Page = (await Browser.StartAsync("bob")).Page.
Signing in once#
A suite that signs in per test spends most of its run signing in. Playwright's storage state, the
cookies and local storage of a signed-in context, turns that into one sign-in for the whole run.
IPreceptStartup.BeforeRunAsync is where it happens:
public async Task BeforeRunAsync(IServiceProvider services)
{
await using var session = await services.GetRequiredService<BrowserFactory>().NewSessionAsync();
await session.Page.GotoAsync("/sign-in");
await session.Page.GetByLabel("Email").FillAsync("qa@example.com");
await session.Page.GetByLabel("Password").FillAsync(Environment.GetEnvironmentVariable("QA_PASSWORD"));
await session.Page.GetByRole(AriaRole.Button, new() { Name = "Sign in" }).ClickAsync();
await session.SaveStorageStateAsync();
}
Every session started from then on begins signed in. BeforeRunAsync has no test to belong to,
which is why the session comes from BrowserFactory.NewSessionAsync() rather than from Browser.
It records nothing, no trace, no video and no screenshot, because there is no test to attach any of
it to.
The state is filed under the session's name, and a session starts from the state filed under its name. That is what gives a suite two identities:
await using var admin = await factory.NewSessionAsync("admin");
// sign in as an administrator, then:
await admin.SaveStorageStateAsync();
var admin = await Browser.StartAsync("admin"); // already signed in as one
A state produced somewhere else, by a previous run or by a tool outside the suite, is named as a file instead, and seeds the default identity:
{
"Web": { "StorageState": "auth.json" }
}
The path is resolved against the working directory, which is normally the test project's output. A file that is not there fails the run. Seeding silently from nothing would leave every test signed out, with every failure worded as though the application had rejected the credentials.
An application that keeps its sign-in outside cookies and local storage needs more saved. Pass
Playwright's own options and they go to StorageStateAsync unchanged:
await session.SaveStorageStateAsync(new BrowserContextStorageStateOptions { IndexedDB = true, Opfs = true });
IndexedDB adds the page's databases, and Opfs adds its origin private file system.
Keeping a sign-in between runs#
A saved state lasts for the run. To have the next run start signed in too, keep it on disk:
{
"Web": { "KeepStorageStates": "Auto" }
}
| Value | What it does |
|---|---|
Never |
The default. The state is kept in memory, for this run only. |
Auto |
Kept on disk on your own machine. On a build agent, in memory only. |
Always |
Kept on disk everywhere, a build agent too. |
- Where:
PreceptStorageStatesnext to the built test app, for examplebin/Debug/net10.0/PreceptStorageStates. Each session has its own file:default.jsonfor the default session,session-<name>.jsonfor a named one. - Not published: the folder is outside
ArtifactDirectory, so it is not attached to a test, copied into the TRX or uploaded by a reporter. Only your account can read the files. - Loaded once, when the run opens its first browser. Every session then starts from the file
saved under its name. If
StorageStateis set too, it wins for the default session. - Parallel tests share one copy in memory and need no locking. Two runs at the same time each read whole files, and the last save wins.
- A file that cannot be read is deleted, and that session starts signed out.
A kept state can outlive the session on the server, for example when it expires overnight. The test then starts signed out. Use this when your suite signs in again whenever the application shows its sign-in page. To start over, delete the folder.
Auto stays off on a build agent on purpose. A self-hosted agent keeps its folders between builds,
and the next pipeline to use it would start signed in as your test user.
A saved state is never attached to the test as an artifact, whatever else the module attaches. It holds a session cookie or a bearer token, which is the credential itself, and an artifact goes wherever the report goes. It is also kept out of the test's trace and HAR: a session starts from it before anything is recorded.
What the test does after that is recorded as usual, and a signed-in test sends its cookies with every request. See Traces and HARs hold credentials.
What the page says about itself#
Console errors and uncaught exceptions go into the test's own log, where they reach the TRX, a test explorer and every reporter, rather than to a process console that belongs to no test:
[console:error] Failed to load resource: the server responded with a status of 500
[page error] TypeError: order is undefined
ConsoleLogging decides how much of the console is logged:
None |
Nothing from the console is logged. |
Errors |
The error lines only. The default. |
All |
Every message the page writes, whatever its level. |
Errors is the default because an error the test was not failed by is still part of the story of
what went wrong, while the rest of an application's logging is normally noise. All is for the case
where that logging is the only account of what the page thought it was doing. None is for an
application whose steady state is noisy, where the errors make every report bulky rather than one
report useful:
{
"Web": { "ConsoleLogging": "None" }
}
The setting decides what is written down, not what is watched. Console errors are collected at every
level, so the session still carries them and FailOnConsoleErrors still fails on them and lists
them. Uncaught page exceptions are logged at every level too, because no application has a steady
state that throws them.
Either can also decide the verdict:
{
"Web": { "FailOnConsoleErrors": true, "FailOnPageErrors": true }
}
Both are off by default. An application with an error in its steady state would fail every test at
once and teach the team to ignore the suite. FailOnPageErrors is the narrower net and the
stronger signal: an uncaught exception is a bug on the page rather than something the application
chose to log. The check runs
after the test's last line, so a
test that passed every assertion and left a broken page still fails, and still gets its failure
screenshot and trace.
The errors are on the session as well, for a test that would rather assert on them than be failed by them:
await Assert.That(Browser.Current!.ConsoleErrors).ToBeEmptyAsync();
What a test records#
A browser test can leave four kinds of file behind. Each one is a setting with the same three values:
| Value | What it does |
|---|---|
Never |
Nothing is recorded. |
OnFailure |
Recorded, kept only when the test fails. |
Always |
Recorded, kept whatever the outcome. |
| Setting | Default | The file |
|---|---|---|
Screenshot |
OnFailure |
failure.png, or screenshot.png after a test that passed. |
Trace |
OnFailure |
trace.zip, opened in the Playwright trace viewer. |
Video |
Never |
The recording of the whole test. |
Har |
Never |
network.har, the session's network traffic. |
{
"Web": { "Video": "Always", "Har": "OnFailure" }
}
The trace, the video and the HAR have to cover the whole test, so they run from the first line
whenever the value is not Never. A failure cannot be recorded from the moment it happens. The
value decides what becomes of the file at the end, not whether the browser was recording.
Video and HAR are off because the trace already carries both the screen and the requests, and it is searchable. Turn the HAR on when the traffic is read somewhere else: by an API team, in a browser's own network panel, or by a tool that reads HARs.
Three more settings shape what is recorded. None of them turns a recording on:
| Setting | Default | What it does |
|---|---|---|
TraceAriaSnapshots |
false |
Adds the page's accessibility tree to the trace for every action. The trace viewer shows it beside the DOM snapshot, which answers what GetByRole saw. |
TraceScreenSnapshots |
false |
Adds a screenshot to the trace for every action. Use it for a canvas, a video or a WebGL scene, which a DOM snapshot cannot replay. It stores images for every action, so the trace becomes several times larger. |
VideoFps |
not set | Frames a second in the video. Playwright records 25 when it is not set. A lower number makes smaller files. Firefox and WebKit record at most 25. |
{
"Web": { "TraceAriaSnapshots": true, "Video": "OnFailure", "VideoFps": 10 }
}
Always is for a run whose files are the point: a regulated release, or a record of what was
exercised. Every test then keeps its files, so a large suite costs a large amount of disk, and
upload time wherever a reporter attaches artifacts.
The files land in the test's artifact directory and are listed with its result; see
Artifacts and logging. A named session
puts its name in the file name, so alice and bob do not overwrite each other.
Traces and HARs hold credentials#
A trace and a HAR record everything the test did, and that includes what a password manager would keep:
- Typed text. A value passed to
FillAsyncis in the trace as it was typed, a password included, and in the request that sent the form. - Cookies and headers. Every request is recorded with its
CookieandAuthorizationheaders, and every response with itsSet-Cookie. A signed-in test's session cookie is in both files. - Request and response bodies. A token the application receives, or sends, is in them.
Anyone who can open the file can sign in as the test's user until the session expires, and can read any password it typed. Precept does not edit these files. Removing every secret from them would need a change at each place Playwright writes one, and a file that has been partly cleaned still looks safe when it is not.
Treat them like a password:
- Run browser tests against test accounts in a test environment, never against a real user or a production account.
- Set
TraceandHartoNeverwhere the report is read by more people than should have those accounts. A trace is copied into the TRX and the pipeline's attachments, and a reporter uploads it, so on a build agent the setting itself is what keeps it in. Set it in the agent's overlay, or asPRECEPT_WEB__TRACE=Never. - To keep traces on disk but out of a reporter, set that reporter's
AttachArtifactstofalse. See What gets attached.
Files the page produced#
A file the page downloads is saved into the test's artifacts and reported with it. Playwright
deletes a download when its context closes, which is the end of the test, so without this the
export a test just triggered would be gone by the time anyone reads the report. Turn it off with
"SaveDownloads": false.
The copy is waited for as the test tears down, for no longer than TimeoutMilliseconds. A download
the server never finishes sending is logged as missing from the artifacts instead of holding the
test open.
A browser somewhere else#
{
"Web": { "WsEndpoint": "ws://grid.internal:3000/" }
}
A browser grid, or a vendor's cloud, is connected to rather than launched. CdpEndpoint connects
to a running Chromium over the DevTools protocol instead, for example http://localhost:9222 to
drive a browser that is already open. Prefer WsEndpoint where both would work, because the
DevTools protocol is the browser's own rather than Playwright's and supports less of it.
WsEndpoint wins when both are set.
Connecting replaces launching, so everything about starting a process stops applying: Headless,
Args, Channel, Proxy and InstallBrowsers all describe a browser this machine is no longer
starting. What a context is opened with still applies, because the context is still the suite's to
describe.
Viewport size#
Every test gets its own browser context, and each one is opened at a fixed viewport. The viewport is the size the page believes it has, which is what a media query, a layout and a screenshot go by. It is not an operating-system window, so it means the same headless as headed.
Name it as a resolution:
{
"Web": { "Resolution": "1080p" }
}
720p, 900p, 1080p, 1440p and 2160p are understood, as are the aliases hd, fhd, qhd,
uhd and 4k. Names are matched however they were typed. Anything else is written as a pair,
1366x768, which is how to reach a size no name covers:
{
"Web": { "Resolution": "1366x768" }
}
A value that is neither fails the run with a message about Web:Resolution. The alternative would
be a suite that quietly ran at some other size, and a viewport is a setting whose effect is only
visible in a screenshot taken after the run.
Resolution is unset by default. Then ViewportWidth and ViewportHeight decide the viewport,
1280 by 800 unless a project says otherwise:
{
"Web": { "ViewportWidth": 1440, "ViewportHeight": 900 }
}
When a resolution is named it decides both, and those two are ignored. That lets a pipeline set
PRECEPT_WEB__RESOLUTION without knowing what the settings file already says. An overlay or an
environment variable cannot clear numbers it cannot see, and a run should not end up with a width
from one file and a height from another.
A Device outranks the two numbers for the same reason: they have defaults, and a default cannot be
told apart from a deliberate 1280 by 800. A named Resolution outranks the device. The most specific
statement of a size wins.
What else a context is opened with#
The context is opened for the test rather than by it, so anything the browser needs to be told before the first navigation is a setting rather than something test code can arrange.
Locale and time#
{
"Web": { "Locale": "en-GB", "TimezoneId": "Europe/London", "ColorScheme": "dark" }
}
Locale is a BCP 47 tag. It decides the Accept-Language header and how the page formats dates and
numbers. TimezoneId is an IANA name. Both are worth setting even where the application is
single-language and single-region: unset, they are the machine's, so an assertion about a formatted
date can pass on a laptop and fail on an agent elsewhere, with a failure that reads like a bug in
the page. ColorScheme is light, dark or no-preference, and is what the page's
prefers-color-scheme media queries see.
Position and permissions#
{
"Web": { "Geolocation": "51.5074,-0.1278", "Permissions": "clipboard-read notifications" }
}
Geolocation is one value, LATITUDE,LONGITUDE, for the same reason Resolution is one: a
coordinate is a pair or it is nothing, and a variable that could set only the latitude would put a
run somewhere neither file meant. Setting it also grants the geolocation permission. Without that
the page would be refused the position rather than given it, and the setting would look ignored.
Permissions are separated by spaces or commas and granted to every context up front, which is
what stops a permission prompt no test can click. The names are the browser's own and are passed
through untouched, so one the browser does not recognise fails the context rather than being
ignored.
Reaching a protected environment#
{
"Web": {
"IgnoreHttpsErrors": true,
"HttpCredentials": { "Username": "qa", "Origin": "https://staging.example.com" },
"Headers": { "X-Test-Run": "nightly" }
}
}
IgnoreHttpsErrors makes an environment behind a self-signed or internally issued certificate
reachable. Leave it off where the certificate is real. HttpCredentials answers HTTP basic
authentication, and its Origin keeps the credentials from being offered to a third-party host the
page loads an asset from. Headers are added to every request the context makes: an API gateway
key, a feature-flag override, the header a test environment identifies its callers by.
The password belongs in PRECEPT_WEB__HTTPCREDENTIALS__PASSWORD rather than in a file the repository
carries. See Environment variables for how a
setting maps onto a variable name.
When more than one host asks for credentials, list them in HttpCredentialsList, each with its
Origin:
{
"Web": {
"HttpCredentialsList": [
{ "Username": "qa", "Origin": "https://staging.example.com" },
{ "Username": "reports", "Origin": "https://reports.example.com" }
]
}
}
The first entry whose origin matches a request is used, and an entry with no Origin matches every
request. HttpCredentials can be set as well. It is tried after the list, so it answers for any
host the list does not name. The first entry's password is PRECEPT_WEB__HTTPCREDENTIALSLIST__0__PASSWORD,
the second's ends __1__PASSWORD.
Headers is a JSON object rather than the one-string form Args uses, because configuration keys
an object by name. An overlay adding a header keeps the ones underneath it and replaces only the
header it names. That is the merge an array cannot give.
Through a proxy#
{
"Web": { "Proxy": { "Server": "http://proxy.internal:8080", "Bypass": "localhost,*.internal" } }
}
The proxy is applied when the browser is launched rather than per context, because the browser is
launched once for the run and a process-wide connection setting cannot vary per test. Username
and Password go alongside Server where the proxy authenticates. Bypass is normally where a
container or a local stub goes, since a proxy cannot route to the agent's own loopback.
Browser switches#
Anything with no setting of its own, and only for Chromium, goes to the browser process as a command line:
{
"Web": { "Args": "--disable-dev-shm-usage --lang=de-DE" }
}
These reach the process, so they are run-wide. Precept launches one browser and gives each test its own context, and a process argument cannot vary per context. They are the engine's own flags, passed through untouched. Playwright neither validates them nor translates them between engines, and Chromium ignores a switch it does not recognise rather than failing. A typo therefore costs a run that quietly did not do what the flag asked, so prefer a real setting where one exists.
Quoting groups a value carrying spaces, and either quote character works:
--user-agent='Mozilla/5.0 (X11; Linux)' arrives as one argument. Single quotes are easier, since a
double quote has to be escaped to survive JSON. A backslash is a path separator rather than an
escape, so --disk-cache-dir=C:\cache means what it says. A quote that is never closed fails the run
with a message about Web:Args rather than reaching a browser as a mangled flag list.
The Playwright version#
Precept.Web ships Playwright 1.64. A test works with Playwright's own IPage and ILocator, so
what a Playwright release adds is there to use without waiting for Precept to wrap it. Since 1.62:
| What | How to use it |
|---|---|
| A locator inside another | row.Within(table) searches for row inside table. |
| Only the visible matches | locator.Visible replaces the :visible CSS pseudo-class. |
| An element in any frame | page.FrameLocator() with no selector searches every frame under the page. It fails when the rest of the locator matches in more than one frame. |
| An element by its aria ref | page.GetByRef("e2"), with a ref taken from an aria snapshot. |
| A dialog closing | The DialogClosed event on a page and on a context. |
| Shadow DOM in the page source | page.ContentAsync(new() { IncludeShadow = true }). |
| Tools a page registers through WebMCP | page.Webmcp. Chromium needs "Args": "--enable-features=WebMCP". |
Moving to this version changes four things a suite may notice:
- An element inside a hidden iframe now counts as hidden.
ToBeVisibleAsyncfails for it, and an action waits for it, where both used to go through. - The browsers are newer: Chromium 156, Firefox 157 and WebKit 27.2. With
InstallBrowsersset toNever, install them again before the first run. - Videos are encoded as VP9 instead of VP8. They are still
.webmfiles. - Ubuntu 20.04 is no longer supported, and on Linux arm64 Chromium is the Chrome for Testing build.
Playwright's release notes have the full list.