webship-js 2.0.13 → 2.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,8 @@
1
1
  # AI Agent Guide — Wisdom from the Recipes Book
2
2
 
3
- This page distills the canonical guidance from
4
- **Webship-js-Recipes v1.0.30** (583 pages, 35 chapters, 340+ recipes) into
3
+ This page distills the canonical guidance from the book
4
+ **Automated Functional Testing Recipes**, in its v1.0.30 edition (then
5
+ titled *Webship-js-Recipes*: 583 pages, 35 chapters, 340+ recipes), into
5
6
  a compact reference for AI coding assistants working on any webship-js
6
7
  project.
7
8
 
@@ -339,7 +340,11 @@ Master the loop.
339
340
 
340
341
  ## Source
341
342
 
342
- This page summarises *Webship-js-Recipes v1.0.30* — chapters 1, 7, 21,
343
- 24, 26, 29, 30, 31, 33, 34, 35 plus appendices. The full PDF lives at
344
- `/home/rajab/Desktop/w-book/Webship-js-Recipes-v1.0.30.pdf`. The
345
- chapter Markdown sources live at `/home/rajab/Desktop/w-book/chapters/`.
343
+ This page summarises the v1.0.30 edition of the book (then titled
344
+ *Webship-js-Recipes*): chapters 1, 7, 21, 24, 26, 29, 30, 31, 33, 34, 35
345
+ plus appendices. The book, *Automated Functional Testing Recipes*, ships
346
+ in Markdown with the webship-js AI agent
347
+ ([webship/webship-js-ai-agent](https://github.com/webship/webship-js-ai-agent))
348
+ and skills ([webship/webship-js-skills](https://github.com/webship/webship-js-skills))
349
+ as the folder `automated-functional-testing-recipes/`; their
350
+ `install-book.sh` copies it to `.claude/automated-functional-testing-recipes/`.
@@ -16,6 +16,8 @@ The "Then I should be" group contains four primary variations:
16
16
 
17
17
  Each step allows testers to validate whether the current page matches expected navigation outcomes.
18
18
 
19
+ **The homepage** is `launchUrl`, or the address `launchUrl` redirects to (a site that sends `/` to a language prefix such as `/en/`); the query, the fragment and a trailing slash do not count. Any other page of the site is not the homepage: check it with `Then I should be on "/path"`. The homepage steps wait up to 5 seconds for a navigation in progress (the back button, a redirect after a form).
20
+
19
21
  ## Purpose
20
22
 
21
23
  These assertions verify successful navigation by confirming the user's location within the website after executing actions like clicking links, submitting forms, or using browser controls. They serve as validation checkpoints in automated testing workflows.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webship-js",
3
- "version": "2.0.13",
3
+ "version": "2.0.14",
4
4
  "description": "Webship JS automated functional testing.",
5
5
  "main": "index.js",
6
6
  "bin": {
@@ -0,0 +1,20 @@
1
+ Feature: An example to ensure that a page is or is not the homepage
2
+ As an anonymous user,
3
+ I want the homepage assertion to tell the homepage from the other pages
4
+
5
+ Scenario: Another page of the site is not the homepage
6
+ Given I am on the homepage
7
+ When I go to "/about-us.html"
8
+ Then I should not be on the homepage
9
+ And I should be on "/about-us.html"
10
+
11
+ Scenario: The query and the fragment of the address do not count
12
+ Given I am on "/?ref=menu#top"
13
+ Then I should be on the homepage
14
+ And I should not be on "/about-us.html"
15
+
16
+ Scenario: Back on the homepage after another page
17
+ Given I am on the homepage
18
+ When I go to "/about-us.html"
19
+ And I move backward one page
20
+ Then I should be on the homepage
@@ -0,0 +1,15 @@
1
+ @must-fail
2
+ Feature: The homepage assertion must fail on another page, and on the homepage in its negative form
3
+ The homepage is launchUrl (or the address it redirects to). Another page of
4
+ the site is not the homepage. tests/check-must-fail.js checks the message,
5
+ the page and the hint.
6
+
7
+ Scenario: Another page of the site is not the homepage
8
+ Fails with: Expected to be on the homepage, but the page is another one.
9
+ Given I am on "/about-us.html"
10
+ Then I should be on the homepage
11
+
12
+ Scenario: The homepage is the homepage
13
+ Fails with: Expected not to be on the homepage, but the page is the homepage.
14
+ Given I am on the homepage
15
+ Then I should not be on the homepage
@@ -6,7 +6,7 @@
6
6
 
7
7
  const { Given, When, Then } = require('@cucumber/cucumber');
8
8
  const assert = require('assert');
9
- const { gotoUrl, resolveUrl, waitForPageLoad, smartSettle } = require('./webship');
9
+ const { gotoUrl, resolveUrl, waitForPageLoad, smartSettle, failure } = require('./webship');
10
10
 
11
11
  // ---------------------------------------------------------------------------
12
12
  // Sessions / visits
@@ -165,7 +165,49 @@ When(/^(I |we )*reload( the)*( page)*$/, async function (pronounCase, theCase, p
165
165
  // ---------------------------------------------------------------------------
166
166
 
167
167
  /**
168
- * Assert that the current page is or is not the homepage.
168
+ * The address of a page without its query and fragment, its path ending in a
169
+ * slash: "https://site.example/en" and "https://site.example/en/?a=1#top"
170
+ * are the same page.
171
+ *
172
+ * @param {string} url
173
+ * @returns {string}
174
+ */
175
+ function pageAddress(url) {
176
+ try {
177
+ const parsed = new URL(url);
178
+ return parsed.origin + (parsed.pathname.endsWith('/') ? parsed.pathname : parsed.pathname + '/');
179
+ } catch {
180
+ return String(url);
181
+ }
182
+ }
183
+
184
+ /**
185
+ * The addresses that are the homepage: `launchUrl`, and the address it
186
+ * redirects to (a site that sends "/" to a language prefix such as "/en/").
187
+ * Asked once per scenario.
188
+ *
189
+ * @param {object} world
190
+ * @returns {Promise<string[]>}
191
+ */
192
+ async function homepageAddresses(world) {
193
+ if (world.homepageAddresses) return world.homepageAddresses;
194
+ const addresses = [pageAddress(world.launchUrl)];
195
+ try {
196
+ const response = await world.page.request.get(world.launchUrl, { maxRedirects: 10, failOnStatusCode: false, timeout: 10000 });
197
+ const landed = pageAddress(response.url());
198
+ if (!addresses.includes(landed)) addresses.push(landed);
199
+ } catch { /* launchUrl alone */ }
200
+ world.homepageAddresses = addresses;
201
+ return addresses;
202
+ }
203
+
204
+ /**
205
+ * Assert that the current page is or is not the homepage: `launchUrl`, or the
206
+ * address `launchUrl` redirects to (a language prefix such as "/en/"). The
207
+ * query and the fragment do not count, nor a trailing slash. The step waits
208
+ * up to 5 seconds for a navigation in progress (the back button, a redirect
209
+ * after a form). Any other page of the site is not the homepage; assert it
210
+ * with `I should be on "/path"`.
169
211
  *
170
212
  * Example #1: Then I should be on homepage
171
213
  * Example #2: And I should be on the homepage
@@ -180,14 +222,22 @@ When(/^(I |we )*reload( the)*( page)*$/, async function (pronounCase, theCase, p
180
222
  *
181
223
  */
182
224
  Then(/^(I |we )*should( not)* be on( the)* (homepage|frontpage)$/, async function (pronounCase, notCase, theCase, pageCase) {
183
- const currentUrl = this.page.url();
184
- if (notCase) {
185
- assert.ok(currentUrl !== this.launchUrl && !currentUrl.startsWith(this.launchUrl + '/'),
186
- `Should NOT be on homepage but current URL is: ${currentUrl}`);
187
- } else {
188
- assert.ok(currentUrl.startsWith(this.launchUrl),
189
- `Should be on homepage but current URL is: ${currentUrl}`);
225
+ const homes = await homepageAddresses(this);
226
+ const deadline = Date.now() + 5000;
227
+ for (;;) {
228
+ const onHome = homes.includes(pageAddress(this.page.url()));
229
+ if (notCase ? !onHome : onHome) return;
230
+ if (Date.now() > deadline) break;
231
+ await new Promise((resolve) => setTimeout(resolve, 100));
190
232
  }
233
+ throw failure(this.page, notCase
234
+ ? 'Expected not to be on the homepage, but the page is the homepage.'
235
+ : 'Expected to be on the homepage, but the page is another one.', {
236
+ found: `the homepage is ${homes.join(' or ')}`,
237
+ hint: notCase
238
+ ? 'The homepage is launchUrl, or the address launchUrl redirects to.'
239
+ : 'The homepage is launchUrl, or the address launchUrl redirects to; the query, the fragment and a trailing slash do not count. To check another page, use: Then I should be on "/path".',
240
+ });
191
241
  });
192
242
 
193
243
  /**