@webship-js/django-cms-steps 2.0.0-beta1 → 2.0.0-rc1

package/README.md

@@ -39,7 +39,7 @@ module.exports = {
     paths: ['tests/features/**/*.feature'],
     worldParameters: {
       launchUrl: process.env.LAUNCH_URL || 'http://localhost',
-      // Accounts for "a logged in user with the username "<key>"". Keep the
+      // Accounts for "a logged in user with the "<key>" user". Keep the
       // password out of the repo: read it from an environment variable.
       users: {
         admin: {
@@ -58,7 +58,7 @@ Then write a feature using the new steps:
 Feature: CMS toolbar
 
   Scenario: Admin sees the CMS toolbar and opens the page tree
-    Given I am a logged in user with the username "admin"
+    Given I am a logged in user with the "admin" user
     Then I should see the CMS toolbar
     When I click "Pages" in the CMS toolbar menu
     Then the CMS sideframe should be showing "/admin/cms/pagecontent/"
@@ -72,19 +72,29 @@ npx cucumber-js --config cucumber.js
 
 | Step | Type |
 | --- | --- |
-| `I am a logged in user with the username "<key>"` (reads `worldParameters.users`) | Given |
+| `I am a logged in user with the "<key>" user` (reads `worldParameters.users`) | Given |
 | `I am not logged in` (clears cookies and storage, asserts the admin login form) | Given |
 | `I log out` | When |
-| `I should see the CMS toolbar` / `I should not see the CMS toolbar` | Then |
+| `I should( not) see the CMS toolbar` | Then |
 | `I click "<label>" in the CMS toolbar menu` | When |
-| `the CMS sideframe should be showing "<url part>"` | Then |
-| `I am on the django CMS page tree` | Given |
-| `I should see the page tree` | Then |
-| `I should see "<title>" in the page tree` | Then |
-| `I should see the django CMS welcome screen` | Then |
-
-Every step's regex and Gherkin examples are in the JSDoc block above it in
-[`tests/step-definitions/django-cms.steps.js`](tests/step-definitions/django-cms.steps.js).
+| `the CMS sideframe should( not) be showing "<url part>"` | Then |
+| `I am on the page tree` | Given |
+| `I should( not) see the page tree` | Then |
+| `I should( not) see "<title>" in the page tree` | Then |
+| `I should( not) see the welcome screen` | Then |
+
+The product word is optional in every sentence: "the CMS toolbar", "the
+django CMS toolbar" and "the toolbar" all match, so a feature written for
+another pack reads here too. Every Then step takes `should` or `should not`,
+every When/Then step takes `I`, `we` or no pronoun, and every failure is a
+friendly message with a hint (no Playwright stack). Assertions wait on their
+locator for the `minWaitTime.page` budget (at least 10 s) instead of reading
+the page once.
+
+Every step's regex and five Gherkin examples are in the JSDoc block above it in
+[`tests/step-definitions/django-cms.steps.js`](tests/step-definitions/django-cms.steps.js);
+`npm run test:examples` checks that each example matches its own step (and no
+webship-js core step) and that every feature step is defined exactly once.
 
 ## Testing this package itself
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webship-js/django-cms-steps",
-  "version": "2.0.0-beta1",
+  "version": "2.0.0-rc1",
   "description": "Custom webship-js step definitions for testing django CMS sites (admin login, the CMS toolbar, toolbar navigation, and the page tree).",
   "main": "index.js",
   "files": [
@@ -14,6 +14,7 @@
     "test:chromium": "BROWSER=chromium cucumber-js --config cucumber.js",
     "test:firefox": "BROWSER=firefox cucumber-js --config cucumber.js",
     "test:webkit": "BROWSER=webkit cucumber-js --config cucumber.js",
+    "test:examples": "node scripts/check-examples.js",
     "report": "generate-reports"
   },
   "keywords": [

package/tests/step-definitions/django-cms.steps.js

@@ -14,12 +14,17 @@
  * Selectors below were captured against a real django CMS 5 install
  * (Django admin login form, the `#cms-top` / `.cms-toolbar` toolbar, and
  * the `.cms-pagetree` page-tree admin). Every step documents its Gherkin
- * phrasing in the JSDoc block right above it.
+ * phrasing in the JSDoc block right above it. The product word is optional
+ * in every sentence ("the CMS toolbar", "the page tree", "the welcome
+ * screen"), so a feature written for another pack reads here too.
+ *
+ * Every assertion waits on its locator (the assertion is the wait), and
+ * every failure is a friendly error with a hint instead of a raw Playwright
+ * timeout stack.
  */
 
 const { Given, When, Then } = require('@cucumber/cucumber');
-const assert = require('assert');
-const { gotoUrl, smartSettle } = require('webship-js/tests/step-definitions/webship');
+const { gotoUrl, smartSettle, friendly } = require('webship-js/tests/step-definitions/webship');
 
 // ---------------------------------------------------------------------------
 // Shared selectors (django CMS toolbar / Django admin)
@@ -41,37 +46,73 @@ const SELECTORS = {
   pageTreeEmpty: '.cms-pagetree-empty',
   // The "no pages yet" welcome screen shown on a fresh install.
   welcomeScreen: '.cms-welcome-heading, .cms-welcome-section, .cms-welcome, #cms-welcome-config',
+  welcomePart: '.cms-welcome-heading, .cms-welcome-section, #cms-welcome-config',
 };
 
+const TOOLBAR_HINT = 'The CMS toolbar (`#cms-top`) only renders for a logged-in staff user on a page served through the CMS; log in first and check the toolbar markup.';
+
 function siteRoot(launchUrl) {
   return String(launchUrl).replace(/\/$/, '');
 }
 
+/** The per-assertion wait budget: `minWaitTime.page` from cucumber.js, else 10 s. */
+function budget(world) {
+  return Math.max((world.minWaitTime && world.minWaitTime.page) || 0, 10000);
+}
+
 async function settle(world, fallback) {
   await smartSettle(world.page, (world.minWaitTime && world.minWaitTime.page) || fallback || 3000);
 }
 
+/**
+ * Run a locator action and rethrow as a friendly error (action, target,
+ * cause and a hint) instead of Playwright's raw timeout stack.
+ */
+async function actOrExplain(label, target, fn, hint) {
+  try {
+    return await fn();
+  } catch (err) {
+    throw friendly({ action: label, target, cause: err, hint });
+  }
+}
+
+/**
+ * Wait until `locator` has (or, with `notCase`, has no) match in the given
+ * state, then throw a friendly error otherwise: the wait and the assertion
+ * are one call.
+ */
+async function assertPresence(locator, notCase, { label, hint, timeout, state = 'visible' }) {
+  try {
+    await locator.first().waitFor({ state: notCase ? (state === 'attached' ? 'detached' : 'hidden') : state, timeout });
+  } catch {
+    throw friendly({
+      message: notCase ? `Expected not to see ${label}, but it is still on the page.` : `Expected ${label}, but it did not appear within ${timeout} ms.`,
+      hint,
+    });
+  }
+}
+
 /**
  * Look up a named user from cucumber.js worldParameters.users
- * (`{ <key>: { username, password } }`), throwing a helpful error if it is
- * not configured.
+ * (`{ <key>: { username, password } }`), throwing a friendly error with a
+ * hint if it is not configured.
  */
 function resolveUser(parameters, userKey) {
   const users = (parameters && parameters.users) || {};
   const entry = users[userKey];
   if (!entry) {
-    throw new Error(
-      `User "${userKey}" is not configured. Add it to worldParameters.users in cucumber.js. ` +
-        `Known users: ${Object.keys(users).join(', ') || '(none)'}.`
-    );
+    throw friendly({
+      message: `User "${userKey}" is not configured. Known users: ${Object.keys(users).join(', ') || '(none)'}.`,
+      hint: `Add it to worldParameters.users in cucumber.js: users: { ${userKey}: { username: '...', password: process.env.DJANGOCMS_ADMIN_PASSWORD } }.`,
+    });
   }
   const username = entry.username || userKey;
   const password = typeof entry === 'string' ? entry : entry.password;
   if (!password) {
-    throw new Error(
-      `User "${userKey}" has no password configured. Set worldParameters.users.${userKey}.password ` +
-        'in cucumber.js, ideally from an environment variable.'
-    );
+    throw friendly({
+      message: `User "${userKey}" has no password configured.`,
+      hint: `Set worldParameters.users.${userKey}.password in cucumber.js, ideally from an environment variable such as DJANGOCMS_ADMIN_PASSWORD.`,
+    });
   }
   return { username, password };
 }
@@ -80,10 +121,13 @@ function resolveUser(parameters, userKey) {
  * Open the toolbar's site-name dropdown. It opens on click, toggling a
  * "-hover" class via JS; it is not a plain CSS :hover menu.
  */
-async function openToolbarSiteMenu(page) {
-  await page.waitForSelector(SELECTORS.toolbarNav, { state: 'visible', timeout: 10000 });
-  const siteMenu = page.locator(`${SELECTORS.toolbarNav} > li`).first();
-  await siteMenu.click();
+async function openToolbarSiteMenu(world) {
+  const nav = world.page.locator(SELECTORS.toolbarNav);
+  const siteMenu = world.page.locator(`${SELECTORS.toolbarNav} > li`).first();
+  await actOrExplain('open', 'the CMS toolbar site menu', async () => {
+    await nav.waitFor({ state: 'visible', timeout: budget(world) });
+    await siteMenu.click();
+  }, TOOLBAR_HINT);
 }
 
 // ---------------------------------------------------------------------------
@@ -102,33 +146,44 @@ async function openToolbarSiteMenu(page) {
  * installer) serves a single, unprefixed language, so URLs here are bare:
  * no "/en/" (or other language code) segment.
  *
- * Example #1: Given I am a logged in user with the username "admin"
- * Example #2: Given we are a logged in user with username "admin"
+ * Example #1: Given I am a logged in user with the "admin" user
+ * Example #2: Given we are a logged in user with the username "admin"
  * Example #3: Given I am a logged in user with "admin"
- * Example #4: And a logged in user with the username "admin"
+ * Example #4: And a logged in user with username "admin"
  * Example #5: Given I am a logged in user with the username "admin" user
  *
  */
 Given(/^(I am |we are )*a logged in user with( the)*( username)* "([^"]*)?"( user)*$/, async function (pronounCase, theCase, usernameCase, userKey, userCase) {
   const { username, password } = resolveUser(this.parameters, userKey);
   const page = this.page;
+  const timeout = budget(this);
   await gotoUrl(page, `${siteRoot(this.launchUrl)}/admin/login/?next=/`);
-  await page.waitForSelector(SELECTORS.loginUsername, { state: 'visible', timeout: 10000 });
-  await page.fill(SELECTORS.loginUsername, username);
-  await page.fill(SELECTORS.loginPassword, password);
-  await Promise.all([
-    page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {}),
-    page.evaluate((formSelector) => {
-      const submit = document.querySelector(`${formSelector} input[type="submit"], ${formSelector} button[type="submit"]`);
-      if (!submit) throw new Error(`The login form "${formSelector}" has no submit button.`);
-      submit.click();
-    }, SELECTORS.loginForm),
-  ]);
+  await actOrExplain('log in as', username, async () => {
+    await page.locator(SELECTORS.loginUsername).waitFor({ state: 'visible', timeout });
+    await page.fill(SELECTORS.loginUsername, username);
+    await page.fill(SELECTORS.loginPassword, password);
+    await Promise.all([
+      page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {}),
+      page.evaluate((formSelector) => {
+        const submit = document.querySelector(`${formSelector} input[type="submit"], ${formSelector} button[type="submit"]`);
+        if (!submit) throw new Error(`The login form "${formSelector}" has no submit button.`);
+        submit.click();
+      }, SELECTORS.loginForm),
+    ]);
+  }, 'The Django admin login form (`#login-form` with `#id_username` / `#id_password`) must be served at /admin/login/ under `launchUrl`.');
   await settle(this);
-  const stillOnLogin = await page.locator(`${SELECTORS.loginForm} .errornote`).count();
-  if (stillOnLogin) {
-    const text = (await page.locator(`${SELECTORS.loginForm} .errornote`).innerText()).trim();
-    throw new Error(`Login as "${username}" was rejected: ${text}`);
+  // The login has two outcomes: the front end (no login form) or the form
+  // again with Django's `.errornote`. Wait for whichever comes first.
+  const errorNote = page.locator(`${SELECTORS.loginForm} .errornote`);
+  await Promise.race([
+    page.locator(SELECTORS.loginForm).waitFor({ state: 'detached', timeout }),
+    errorNote.waitFor({ state: 'visible', timeout }),
+  ]).catch(() => {});
+  if (await errorNote.isVisible()) {
+    throw friendly({
+      message: `Login as "${username}" was rejected: ${(await errorNote.innerText()).trim()}`,
+      hint: `Check worldParameters.users.${userKey} against the site's admin account (DJANGOCMS_ADMIN_USER / DJANGOCMS_ADMIN_PASSWORD).`,
+    });
   }
 });
 
@@ -156,7 +211,11 @@ Given(/^(I am |we are )*not logged in$/, async function (pronounCase) {
   } else {
     await gotoUrl(this.page, loginUrl);
   }
-  await this.page.waitForSelector(SELECTORS.loginForm, { state: 'visible', timeout: 10000 });
+  await assertPresence(this.page.locator(SELECTORS.loginForm), null, {
+    label: 'the Django admin login form (`#login-form`)',
+    hint: 'Check that `launchUrl` points at the site root (the step opens /admin/login/ under it).',
+    timeout: budget(this),
+  });
   await settle(this, 1000);
 });
 
@@ -171,15 +230,20 @@ Given(/^(I am |we are )*not logged in$/, async function (pronounCase) {
  * Example #1: When I log out
  * Example #2: When we log out
  * Example #3: And I log out
+ * Example #4: When log out
+ * Example #5: And we log out
  *
  */
 When(/^(I |we )*log out$/, async function (pronounCase) {
-  await openToolbarSiteMenu(this.page);
-  const logoutLink = this.page.locator(`${SELECTORS.toolbarNav} a`).filter({ hasText: /Logout/i });
-  await Promise.all([
-    this.page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {}),
-    logoutLink.first().click(),
-  ]);
+  await openToolbarSiteMenu(this);
+  const logoutLink = this.page.locator(`${SELECTORS.toolbarNav} a`).filter({ hasText: /Logout/i }).first();
+  await actOrExplain('click', 'the toolbar "Logout" link', async () => {
+    await logoutLink.waitFor({ state: 'visible', timeout: budget(this) });
+    await Promise.all([
+      this.page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {}),
+      logoutLink.click(),
+    ]);
+  }, 'The "Logout <username>" entry lives in the toolbar site-name menu; you must be logged in first.');
   await settle(this);
 });
 
@@ -193,17 +257,28 @@ When(/^(I |we )*log out$/, async function (pronounCase) {
  *
  * Example #1: Then I should see the CMS toolbar
  * Example #2: Then I should not see the CMS toolbar
- * Example #3: And we should see the CMS toolbar
+ * Example #3: And we should see the django CMS toolbar
  * Example #4: But we should not see the CMS toolbar
+ * Example #5: Then should see the toolbar
  *
  */
-Then(/^(I |we )*should( not)* see the CMS toolbar$/, async function (pronounCase, notCase) {
+Then(/^(I |we )*should( not)* see the (?:(?:django )?CMS )?toolbar$/, async function (pronounCase, notCase) {
   if (notCase) {
-    const count = await this.page.locator(SELECTORS.toolbar).count();
-    assert.strictEqual(count, 0, 'CMS toolbar should not be visible but it is.');
+    // The toolbar is never rendered for an anonymous visitor, so the
+    // negative case waits for the element to be gone from the DOM.
+    await assertPresence(this.page.locator(SELECTORS.toolbar), notCase, {
+      label: 'the CMS toolbar',
+      hint: 'The toolbar is still in the DOM: the session was not cleared, or the logout did not complete.',
+      timeout: budget(this),
+      state: 'attached',
+    });
     return;
   }
-  await this.page.waitForSelector(SELECTORS.toolbarBar, { state: 'visible', timeout: 10000 });
+  await assertPresence(this.page.locator(SELECTORS.toolbarBar), null, {
+    label: 'the CMS toolbar',
+    hint: TOOLBAR_HINT,
+    timeout: budget(this),
+  });
 });
 
 /**
@@ -219,37 +294,52 @@ Then(/^(I |we )*should( not)* see the CMS toolbar$/, async function (pronounCase
  *
  * Example #1: When I click "Pages" in the CMS toolbar menu
  * Example #2: When I click "Users" in the CMS toolbar menu
- * Example #3: And we click "Administration" in the CMS toolbar menu
+ * Example #3: And we click "Administration" in the django CMS toolbar menu
+ * Example #4: When I click "User settings" in the toolbar menu
+ * Example #5: And click "Aliases" in the CMS toolbar menu
  *
  */
-When(/^(I |we )*click "([^"]*)" in the CMS toolbar menu$/, async function (pronounCase, linkText) {
-  await openToolbarSiteMenu(this.page);
+When(/^(I |we )*click "([^"]*)" in the (?:(?:django )?CMS )?toolbar menu$/, async function (pronounCase, linkText) {
+  await openToolbarSiteMenu(this);
   const label = linkText.trim().replace(/[.…]+$/, '');
   const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const link = this.page
     .locator(`${SELECTORS.toolbarNav} a`)
-    .filter({ hasText: new RegExp(`^\\s*${escaped}(?:\\.\\.\\.|…)?\\s*$`, 'i') });
-  await link.first().click();
+    .filter({ hasText: new RegExp(`^\\s*${escaped}(?:\\.\\.\\.|…)?\\s*$`, 'i') })
+    .first();
+  await actOrExplain('click', `"${linkText}" in the CMS toolbar menu`, async () => {
+    await link.waitFor({ state: 'visible', timeout: budget(this) });
+    await link.click();
+  }, 'The label must match a toolbar site-menu entry (e.g. "Pages", "Users", "Administration"); a trailing "..." is optional.');
   await settle(this, 1000);
 });
 
 /**
- * Assert the CMS sideframe overlay is open and its iframe is showing a
- * URL containing the given substring.
+ * Assert the CMS sideframe overlay is (or is not) open with its iframe
+ * showing a URL containing the given substring.
  *
  * Example #1: Then the CMS sideframe should be showing "/admin/cms/pagecontent/"
  * Example #2: Then the CMS sideframe should be showing "/admin/auth/user/"
- * Example #3: And the CMS sideframe should be showing "/admin/"
+ * Example #3: And the django CMS sideframe should be showing "/admin/"
+ * Example #4: Then the sideframe should not be showing "/admin/auth/user/"
+ * Example #5: And the CMS sideframe should not be showing "/admin/cms/pagecontent/"
  *
  */
-Then(/^the CMS sideframe should be showing "([^"]*)"$/, async function (urlSubstring) {
-  const iframe = this.page.locator('.cms-sideframe-frame iframe').first();
-  await iframe.waitFor({ state: 'attached', timeout: 10000 });
-  const src = await iframe.getAttribute('src');
-  assert.ok(
-    src && src.includes(urlSubstring),
-    `Expected the CMS sideframe to be showing a URL containing "${urlSubstring}" but it was showing "${src}".`
-  );
+Then(/^the (?:(?:django )?CMS )?sideframe should( not)* be showing "([^"]*)"$/, async function (notCase, urlSubstring) {
+  const frames = this.page.locator('.cms-sideframe-frame iframe');
+  const matching = frames.and(this.page.locator(`[src*="${urlSubstring.replace(/["\\]/g, '\\$&')}"]`));
+  const timeout = budget(this);
+  try {
+    await matching.first().waitFor({ state: notCase ? 'detached' : 'attached', timeout });
+  } catch {
+    const src = await frames.first().getAttribute('src').catch(() => null);
+    throw friendly({
+      message: notCase
+        ? `Expected the CMS sideframe not to be showing a URL containing "${urlSubstring}", but it is ("${src}").`
+        : `Expected the CMS sideframe to be showing a URL containing "${urlSubstring}", but it ${src ? `is showing "${src}"` : 'is not open'}.`,
+      hint: 'Toolbar entries with data-rel="sideframe" open in the `.cms-sideframe` overlay; click one with "click \\"...\\" in the CMS toolbar menu" first.',
+    });
+  }
 });
 
 // ---------------------------------------------------------------------------
@@ -263,38 +353,55 @@ Then(/^the CMS sideframe should be showing "([^"]*)"$/, async function (urlSubst
  * Example #1: Given I am on the django CMS page tree
  * Example #2: Given we are on the django CMS page tree
  * Example #3: And on the django CMS page tree
+ * Example #4: Given I am on the CMS page tree
+ * Example #5: Given I am on the page tree
  *
  */
-Given(/^(I am |we are )*on the django CMS page tree$/, async function (pronounCase) {
+Given(/^(I am |we are )*on the (?:(?:django )?CMS )?page tree$/, async function (pronounCase) {
   await gotoUrl(this.page, `${siteRoot(this.launchUrl)}/admin/cms/pagecontent/`);
   await settle(this);
 });
 
 /**
- * Assert the page tree admin has rendered (either populated or the
- * "no pages yet" empty state).
+ * Assert the page tree admin has (or has not) rendered (either populated
+ * or the "no pages yet" empty state).
  *
  * Example #1: Then I should see the page tree
  * Example #2: Then we should see the page tree
- * Example #3: And should see the page tree
+ * Example #3: And should see the CMS page tree
+ * Example #4: Then I should not see the page tree
+ * Example #5: And we should see the django CMS page tree
  *
  */
-Then(/^(I |we )*should see the page tree$/, async function (pronounCase) {
-  await this.page.waitForSelector(SELECTORS.pageTree, { state: 'visible', timeout: 10000 });
+Then(/^(I |we )*should( not)* see the (?:(?:django )?CMS )?page tree$/, async function (pronounCase, notCase) {
+  await assertPresence(this.page.locator(SELECTORS.pageTree), notCase, {
+    label: 'the page tree (`.cms-pagetree`)',
+    hint: 'The page tree is the change list at /admin/cms/pagecontent/ and needs a logged-in staff user; open it with "I am on the page tree".',
+    timeout: budget(this),
+  });
 });
 
 /**
- * Assert a page with the given title is listed in the page tree.
+ * Assert a page with the given title is (or is not) listed in the page tree.
  *
  * Example #1: Then I should see "Home" in the page tree
  * Example #2: Then we should see "About" in the page tree
  * Example #3: And should see "Contact" in the page tree
+ * Example #4: Then I should not see "Draft" in the page tree
+ * Example #5: And we should see "Home" in the CMS page tree
  *
  */
-Then(/^(I |we )*should see "([^"]*)" in the page tree$/, async function (pronounCase, title) {
-  await this.page.waitForSelector(SELECTORS.pageTree, { state: 'visible', timeout: 10000 });
-  const entry = this.page.locator('.cms-pagetree-jstree').getByText(title, { exact: false });
-  await entry.first().waitFor({ state: 'visible', timeout: 10000 });
+Then(/^(I |we )*should( not)* see "([^"]*)" in the (?:(?:django )?CMS )?page tree$/, async function (pronounCase, notCase, title) {
+  await assertPresence(this.page.locator(SELECTORS.pageTree), null, {
+    label: 'the page tree (`.cms-pagetree`)',
+    hint: 'Open the page tree first with "I am on the page tree".',
+    timeout: budget(this),
+  });
+  await assertPresence(this.page.locator('.cms-pagetree-jstree').getByText(title, { exact: false }), notCase, {
+    label: `a page titled "${title}" in the page tree`,
+    hint: 'Page titles come from the pages the site really has; create the page first or check the spelling.',
+    timeout: budget(this),
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -302,20 +409,26 @@ Then(/^(I |we )*should see "([^"]*)" in the page tree$/, async function (pronoun
 // ---------------------------------------------------------------------------
 
 /**
- * Assert the django CMS "no pages yet" welcome screen is showing. django CMS
- * renders it for the site root while the site has no pages at all, for a
- * signed-in user: its script sends an anonymous visitor to the login form, so
- * log in first.
+ * Assert the django CMS "no pages yet" welcome screen is (or is not)
+ * showing. django CMS renders it for the site root while the site has no
+ * pages at all, for a signed-in user: its script sends an anonymous visitor
+ * to the login form, so log in first.
  *
  * Example #1: Then I should see the django CMS welcome screen
  * Example #2: Then we should see the django CMS welcome screen
- * Example #3: And should see the django CMS welcome screen
+ * Example #3: And should see the CMS welcome screen
+ * Example #4: Then I should see the welcome screen
+ * Example #5: Then I should not see the welcome screen
  *
  */
-Then(/^(I |we )*should see the django CMS welcome screen$/, async function (pronounCase) {
+Then(/^(I |we )*should( not)* see the (?:(?:django )?CMS )?welcome screen$/, async function (pronounCase, notCase) {
   // The welcome wrapper itself can report no box of its own (its parts are positioned), so the
   // assertion is on a part a visitor reads: the heading or a section.
-  await this.page.waitForSelector(SELECTORS.welcomeScreen, { state: 'attached', timeout: 10000 });
-  const part = this.page.locator('.cms-welcome-heading, .cms-welcome-section, #cms-welcome-config').first();
-  await part.waitFor({ state: 'visible', timeout: 10000 });
+  await assertPresence(this.page.locator(SELECTORS.welcomePart), notCase, {
+    label: 'the "no pages yet" welcome screen',
+    hint: notCase
+      ? 'The welcome screen shows while the site has no pages at all; create a page to replace it.'
+      : 'The welcome screen only renders on the site root of a site with no pages, for a signed-in user; log in first.',
+    timeout: budget(this),
+  });
 });