Skip to main content

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:

SpecNameTag
src/sections/pricing/slides/delivery/delivery.e2e.mjspricing/delivery@slide
src/sections/pricing/pricing.e2e.mjspricing@section
src/templates/quote/quote.e2e.mjsquote@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.

warning

A test that calls openTarget before setMode fails:

Choose a mode before calling openTarget, with deck.setMode(...).

Templates​

warning

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.

ModeReproducesChannelsEditable
modes.preso.preppingA preso being prepped, with editables showingpersonal, everyonepersonal
modes.preso.previewingPrep's preview of how a slide looks when presentedpersonal, everyonepersonal
modes.preso.presentingA preso being presented to a customerpersonal, everyonepersonal
modes.preso.reviewingA preso after it has been presentedpersonal, everyonenone
modes.preso.addingUserTemplateA user template dropped into a presopersonal, everyonepersonal, everyone
modes.preso.addingCustomSlideA template dropped into a preso as a custom slide, before the uploadpersonal, everyonepersonal, everyone
modes.preso.addedCustomSlideThe same custom slide, once it is uploadedpersonal, everyonepersonal, everyone
modes.preso.addingTemplatePreviewA template in the preso slide pickereveryonenone
modes.presomanager.editingPresoManager, editing the content every preso starts witheveryoneeveryone
modes.presomanager.previewingPresoManager, with no content enteredeveryoneeveryone
modes.presomanager.placingTemplateA template placed as a slide in PresoManager, before publishingeveryoneeveryone
modes.presomanager.placedTemplateThe same slide, once it is publishedeveryoneeveryone
modes.presomanager.templatePreviewA template in the PresoManager template listeveryonenone
modes.preset.previewingA preset previeweveryonenone
modes.share.onlineA preso shared with a customer by linkpersonal, everyonepersonal
modes.share.remoteA preso a customer joined remotely from their browserpersonal, everyonepersonal
modes.screenshot.thumbnailA slide rendered for a thumbnail capturepersonal, everyonenone
modes.screenshot.pdfA slide rendered for a PDF capturepersonal, everyonenone

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.

EnvKeys
appointmentid, begin, end
tenancyid, name, brand_colour, logo_cropped, logo_original, logo_background_colour
userid, 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();
note

If the slide registered pages for two subslides, showPage throws, because the page number could mean either.