Decks
The deck fixture puts one target on the stage and gives a spec the commands to drive it. Read
end-to-end tests first for the setup.
Naming a spec after its target​
A report reads better when each test says which slide it covers. Call describeTarget in a spec that sits beside the
slide, section or template it drives:
import { describeTarget, test } from "@livepreso/content-testing/playwright";
describeTarget(() => {
test("should show the fee for the delivery speed a customer picks", async ({ deck }) => {
// ...
});
});
The name and the tag come from the folder the spec sits in:
| Spec | Name | Tag |
|---|---|---|
src/sections/pricing/slides/delivery/delivery.e2e.mjs | pricing/delivery | @slide |
src/sections/pricing/pricing.e2e.mjs | pricing | @section |
src/templates/quote/quote.e2e.mjs | quote | @template |
So the delivery spec reports as:
pricing/delivery > should show the fee for the delivery speed a customer picks @slide
Run one kind of spec with its tag:
npm run test:e2e -- --grep @template
The playwright UI filters on the same tags, and on the name, so pricing/ runs that section alone.
A tag of your own goes in the same place, beside the one the target gives:
describeTarget({ tag: "@slow" }, () => {
// ...
});
Example​
import { expect, modes, test } from "@livepreso/content-testing/playwright";
test("should show the fee for the delivery speed a customer picks", async ({ deck }) => {
await deck.setFeeds({ rates: { standard: "$12", express: "$24" } });
await deck.setMode(modes.preso.prepping);
const slide = await deck.openTarget("pricing/delivery");
await slide.locator.getByRole("button", { name: "Express" }).click();
await expect(slide.locator.getByTestId("postage-fee")).toHaveText("$24");
});
The test sets the feeds and the mode, then clicks as a person would, then asserts what the slide shows.
Choosing a mode​
You must pick a mode before opening a target. Every mode is listed under setMode.
Feeds, context, cmsvals and envs set before openTarget are in place when the deck first renders. Setting one after
openTarget re-renders the deck.
A test that calls openTarget before setMode fails:
Choose a mode before calling openTarget, with deck.setMode(...).
Templates​
The CDK supports one instance of a template, so a key with {instance} in it always resolves to instance 1.
deck​
.openTarget(key)​
Puts one target on screen: a slide, a section or a template, named the way the project file names it, the same as
openTarget in a unit test.
Returns: a promise of the target, drawn and settled. For a template key, resolves to the slide the mode created from that template, because that slide has the fields.
Throws: when no mode is chosen yet, and when no target has this key, under the code unknown-target.
const slide = await deck.openTarget("pricing/delivery");
// A template is reachable only on a mode that places one.
await deck.setMode(modes.presomanager.placingTemplate);
const card = await deck.openTarget("price-card");
.setMode(mode)​
Before the first openTarget, sets the mode the deck opens in. After it, re-renders the deck in the new mode.
Returns: a promise that settles once the deck is on that page.
await slide.openField("postage-fee").set({ text: "$12" });
await deck.setMode(modes.preso.prepping);
await expect(slide.locator.getByTestId("postage-fee")).toHaveText("$12");
A mode reproduces one page of the application: Prep, PresoManager, a share link, a screenshot. A slide behaves differently in each. Prep and PresoManager edit different stores, a share shows the finished preso to a customer, and a screenshot renders the slide for capture.
Pick the mode your test is about. The same field is editable in modes.presomanager.editing and read-only in
modes.share.online.
The Channels column lists the channels a mode makes available, and Editable says which
of them a mutation can write. Where a mode makes neither of a field's channels available, openField throws as if the
field did not exist.
| Mode | Reproduces | Channels | Editable |
|---|---|---|---|
modes.preso.prepping | A preso being prepped, with editables showing | personal, everyone | personal |
modes.preso.previewing | Prep's preview of how a slide looks when presented | personal, everyone | personal |
modes.preso.presenting | A preso being presented to a customer | personal, everyone | personal |
modes.preso.reviewing | A preso after it has been presented | personal, everyone | none |
modes.preso.addingUserTemplate | A user template dropped into a preso | personal, everyone | personal, everyone |
modes.preso.addingCustomSlide | A template dropped into a preso as a custom slide, before the upload | personal, everyone | personal, everyone |
modes.preso.addedCustomSlide | The same custom slide, once it is uploaded | personal, everyone | personal, everyone |
modes.preso.addingTemplatePreview | A template in the preso slide picker | everyone | none |
modes.presomanager.editing | PresoManager, editing the content every preso starts with | everyone | everyone |
modes.presomanager.previewing | PresoManager, with no content entered | everyone | everyone |
modes.presomanager.placingTemplate | A template placed as a slide in PresoManager, before publishing | everyone | everyone |
modes.presomanager.placedTemplate | The same slide, once it is published | everyone | everyone |
modes.presomanager.templatePreview | A template in the PresoManager template list | everyone | none |
modes.preset.previewing | A preset preview | everyone | none |
modes.share.online | A preso shared with a customer by link | personal, everyone | personal |
modes.share.remote | A preso a customer joined remotely from their browser | personal, everyone | personal |
modes.screenshot.thumbnail | A slide rendered for a thumbnail capture | personal, everyone | none |
modes.screenshot.pdf | A slide rendered for a PDF capture | personal, everyone | none |
Writing to a channel the mode cannot edit is refused with the code read-only. A template can only be edited where the
mode shows it as an instance or as a custom version of one. Each mode applies the same
body classes as the page it reproduces.
.setContext(context)​
Replaces the context. Keys from an earlier call are dropped.
Returns: a promise that settles once the deck has the value.
await deck.setContext({ customer: { industry: "freight", region: "Benelux" } });
.setFeeds(feeds)​
Sets the feed data the slide reads, keyed by feed name.
Returns: a promise that settles once the deck has the feeds.
Throws: when the name is not a feed the project file declares. The message lists the feeds that are.
This deck declares no feed called "rate". It declares benchmarks, rates.
await deck.setFeeds({ rates: { standard: "$12" } });
.setCmsVals(cmsVals)​
Replaces the CMSVal keys the deck renders with.
Returns: a promise that settles once the deck has the values.
Throws: in a mode that has no cmsvals, such as modes.presomanager.templatePreview.
modes.presomanager.templatePreview renders with no cmsvals, the way that page does in the app.
await deck.setCmsVals({ "delivery-heading": "Delivery" });
.setEnvs(envs)​
Sets envs, the values the app provides to a deck, keyed by env name. Each env merges over the default the CDK supplies, so a key you leave out keeps that default.
| Env | Keys |
|---|---|
appointment | id, begin, end |
tenancy | id, name, brand_colour, logo_cropped, logo_original, logo_background_colour |
user | id, first_name, last_name, email, profile |
customer and contacts are envs too, but setEnvs does not take them. Use setCustomer and setContacts.
Returns: a promise that settles once the deck has them.
Throws: on an unknown env.
"branch" is not an env. There are appointment, tenancy, user.
await deck.setEnvs({ appointment: { begin: "2026-02-18T09:30:00Z" } });
.setCustomer(customer)​
The customer the preso is for: id, title, logo_128, logo_256, logo_512, logo_original, primary_colour and
profile. Pass only the keys the slide reads.
Returns: a promise that settles once the deck has the customer.
Throws: on an unknown key.
await deck.setCustomer({ id: 7, title: "Acme Freight", primary_colour: "4c7a5d" });
.setContacts(contacts)​
The preso's contacts, as an array of objects with the keys id, email, first_name, last_name, phone and
profile.
Returns: a promise that settles once the deck has the contacts.
Throws: on an unknown key.
await deck.setContacts([{ id: 2, first_name: "Sam", email: "sam@example.com" }]);
.clear(store)​
Clears both context and cmsvals. Pass "context" or "cmsVals" to clear only that one.
Returns: a promise that settles once they are cleared.
Throws: on a store name other than context or cmsVals.
await deck.clear();
await deck.clear("context");
slide​
.locator​
The current slide, as a playwright locator.
Returns: a locator.
await expect(slide.locator.getByTestId("postage-fee")).toHaveText("$18");
await expect(slide.locator.getByText("Free over $50")).toBeVisible();
expect(await slide.locator.innerText()).toContain("Free over $50");
.openField(name)​
The field for one editable on this slide. Use openField to set up state before the test, such as filling a field the
slide reads. Do the actions the test is about through the DOM, as a user would. The unit test page
covers the operations in full.
Returns: the field. Call its operations directly. A query returns a promise of its value, and a mutation a promise
that resolves to undefined once the write is applied.
const fee = slide.openField("postage-fee");
await fee.set({ text: "$18" }); // undefined
await fee.get(); // "$18"
.reload()​
Reloads the current slide.
Returns: a promise that settles once the deck has re-rendered.
await slide.reload();
.readPageCount()​
The number of pages the slide registered with Bridge.Navigation.setPages.
Returns: a promise of the count, or of null if the slide never called setPages.
expect(await slide.readPageCount()).toBe(2);
.showPage(number)​
Shows page number of the slide. Pages are numbered from 1.
Returns: a promise that settles once the slide has shown the page.
Throws: when the slide registered no pages.
await slide.showPage(2);
await expect(page.getByText("Page 2")).toBeInViewport();
If the slide registered pages for two subslides, showPage throws, because the page number could mean either.