webship-js 2.0.3 → 2.0.4

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.
Files changed (49) hide show
  1. package/.circleci/config.yml +7 -31
  2. package/.drone.yml +68 -0
  3. package/.harness/webship-js-pipeline.yml +101 -0
  4. package/.semaphore/semaphore.yml +58 -0
  5. package/.teamcity/pom.xml +52 -0
  6. package/.teamcity/settings.kts +92 -0
  7. package/.travis.yml +24 -3
  8. package/AGENTS.md +2 -2
  9. package/CLAUDE.md +2 -2
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/buildspec.yml +56 -0
  14. package/cloudbuild.yaml +49 -0
  15. package/codefresh.yml +77 -0
  16. package/cucumber.js +40 -3
  17. package/docs/04-step-reference.md +74 -3
  18. package/docs/16-ci-cd.md +879 -0
  19. package/docs/README.md +113 -0
  20. package/docs/global-settings.md +51 -0
  21. package/examples/video-demo.html +43 -0
  22. package/package.json +1 -1
  23. package/tests/features/video.feature +18 -0
  24. package/tests/step-definitions/a11y.steps.js +3 -1
  25. package/tests/step-definitions/action.steps.js +2 -2
  26. package/tests/step-definitions/api.steps.js +17 -16
  27. package/tests/step-definitions/assertion.steps.js +2 -2
  28. package/tests/step-definitions/auth.steps.js +3 -1
  29. package/tests/step-definitions/clock.steps.js +38 -38
  30. package/tests/step-definitions/debug.steps.js +13 -5
  31. package/tests/step-definitions/element.steps.js +47 -5
  32. package/tests/step-definitions/file-download.steps.js +38 -20
  33. package/tests/step-definitions/form.steps.js +6 -6
  34. package/tests/step-definitions/iframe.steps.js +65 -15
  35. package/tests/step-definitions/input.steps.js +47 -8
  36. package/tests/step-definitions/javascript.steps.js +195 -34
  37. package/tests/step-definitions/keyboard.steps.js +38 -4
  38. package/tests/step-definitions/modal.steps.js +39 -14
  39. package/tests/step-definitions/network.steps.js +61 -19
  40. package/tests/step-definitions/responsive.steps.js +3 -1
  41. package/tests/step-definitions/selectors.steps.js +19 -17
  42. package/tests/step-definitions/video.steps.js +178 -0
  43. package/tests/step-definitions/web-first.steps.js +3 -1
  44. package/tests/step-definitions/webship.js +234 -15
  45. package/tests/step-definitions/xml.steps.js +4 -2
  46. package/tests/step-definitions/yaml.steps.js +13 -11
  47. package/videos/README.md +32 -0
  48. package/.travis-ci.yml +0 -16
  49. package/docs/index.md +0 -104
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Parse and assert against an XML response loaded from a file or doc string.
4
6
 
5
7
  const { Given, Then, When } = require('@cucumber/cucumber');
@@ -15,8 +17,8 @@ catch (e) {
15
17
  }
16
18
 
17
19
  function ensureXml(world) {
18
- if (!DOMParser) throw new Error('XML steps require an XML DOM parser. Install @xmldom/xmldom.');
19
- if (!world._xml) throw new Error('No XML response has been set.');
20
+ if (!DOMParser) throw friendly('XML steps require an XML DOM parser. Install @xmldom/xmldom.');
21
+ if (!world._xml) throw friendly('No XML response has been set.');
20
22
  return world._xml;
21
23
  }
22
24
 
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Parse and assert against YAML response bodies.
4
6
  //
5
7
  // Mirrors xml.steps.js where it makes sense (path-based existence / equality
@@ -23,13 +25,13 @@ try { Ajv = require('ajv'); } catch { /* lazy */ }
23
25
  try { addFormats = require('ajv-formats'); } catch { /* lazy */ }
24
26
 
25
27
  function requireYaml() {
26
- if (!YAML) throw new Error('YAML steps require js-yaml. Install with: npm i js-yaml');
28
+ if (!YAML) throw friendly('YAML steps require js-yaml. Install with: npm i js-yaml');
27
29
  return YAML;
28
30
  }
29
31
 
30
32
  function ensureLoaded(world) {
31
33
  requireYaml();
32
- if (world._yaml === undefined) throw new Error('No YAML response has been set.');
34
+ if (world._yaml === undefined) throw friendly('No YAML response has been set.');
33
35
  return world._yaml;
34
36
  }
35
37
 
@@ -181,10 +183,10 @@ Given('the YAML response content is the following:', async function (docString)
181
183
  *
182
184
  */
183
185
  Given('the active YAML document is {int}', function (n) {
184
- if (!this._yamlDocs) throw new Error('No YAML response has been set.');
186
+ if (!this._yamlDocs) throw friendly('No YAML response has been set.');
185
187
  const idx = n - 1;
186
188
  if (idx < 0 || idx >= this._yamlDocs.length) {
187
- throw new Error(`Document ${n} out of range (have ${this._yamlDocs.length}).`);
189
+ throw friendly(`Document ${n} out of range (have ${this._yamlDocs.length}).`);
188
190
  }
189
191
  this._yamlDocIndex = idx;
190
192
  this._yaml = this._yamlDocs[idx];
@@ -581,10 +583,10 @@ Then('the YAML value at {string} should not be empty', function (p) {
581
583
 
582
584
  function numAt(doc, p) {
583
585
  const nodes = evalPath(doc, p);
584
- if (nodes.length === 0) throw new Error(`YAML element "${p}" not found.`);
586
+ if (nodes.length === 0) throw friendly(`YAML element "${p}" not found.`);
585
587
  const v = nodes[0];
586
588
  const n = typeof v === 'number' ? v : Number(v);
587
- if (!Number.isFinite(n)) throw new Error(`YAML value at "${p}" is not numeric: ${v}`);
589
+ if (!Number.isFinite(n)) throw friendly(`YAML value at "${p}" is not numeric: ${v}`);
588
590
  return n;
589
591
  }
590
592
 
@@ -670,9 +672,9 @@ Then('the YAML value at {string} should be between {float} and {float}', functio
670
672
 
671
673
  function arrayAt(doc, p) {
672
674
  const nodes = evalPath(doc, p);
673
- if (nodes.length === 0) throw new Error(`YAML element "${p}" not found.`);
675
+ if (nodes.length === 0) throw friendly(`YAML element "${p}" not found.`);
674
676
  const v = nodes[0];
675
- if (!Array.isArray(v)) throw new Error(`YAML value at "${p}" is not an array.`);
677
+ if (!Array.isArray(v)) throw friendly(`YAML value at "${p}" is not an array.`);
676
678
  return v;
677
679
  }
678
680
 
@@ -737,10 +739,10 @@ Then('every item in {string} should have key {string}', function (p, key) {
737
739
 
738
740
  function keysAt(doc, p) {
739
741
  const nodes = evalPath(doc, p);
740
- if (nodes.length === 0) throw new Error(`YAML element "${p}" not found.`);
742
+ if (nodes.length === 0) throw friendly(`YAML element "${p}" not found.`);
741
743
  const v = nodes[0];
742
744
  if (typeof v !== 'object' || Array.isArray(v) || v === null) {
743
- throw new Error(`YAML value at "${p}" is not a mapping.`);
745
+ throw friendly(`YAML value at "${p}" is not a mapping.`);
744
746
  }
745
747
  return Object.keys(v);
746
748
  }
@@ -796,7 +798,7 @@ Then('the YAML at {string} should have keys {string}', function (p, csv) {
796
798
  *
797
799
  */
798
800
  Then('the YAML should match JSON Schema {string}', function (schemaFile) {
799
- if (!Ajv) throw new Error('Schema validation requires ajv. Install with: npm i ajv ajv-formats');
801
+ if (!Ajv) throw friendly('Schema validation requires ajv. Install with: npm i ajv ajv-formats');
800
802
  const doc = activeDoc(this); ensureLoaded(this);
801
803
  const p = path.isAbsolute(schemaFile) ? schemaFile : path.join(this.assetsFolder || './tests/assets', schemaFile);
802
804
  const schema = JSON.parse(fs.readFileSync(p, 'utf-8'));
@@ -0,0 +1,32 @@
1
+ # videos/
2
+
3
+ Generated by Playwright when video recording is enabled. Default mode is
4
+ **off** — this directory stays empty unless you opt in.
5
+
6
+ ## Enable recording
7
+
8
+ | How | Effect |
9
+ | --- | --- |
10
+ | `WEBSHIP_VIDEO=on npm test` | Record every scenario in this run. |
11
+ | `WEBSHIP_VIDEO=on-failure npm test` | Record every scenario, keep only failures. |
12
+ | Tag scenario `@video` | Force-record this one scenario (mode-independent). |
13
+ | `worldParameters.video.mode = 'on'` in `cucumber.js` | Persist recording for every run. |
14
+
15
+ ## File naming
16
+
17
+ Default template: `{datetime}.{feature_file}.{scenario}.{status}.{ext}` —
18
+ e.g. `2026-05-13T01-47-01-567Z.video.Record_a_tiny_click_flow_with_emojis.PASSED.webm`.
19
+
20
+ Mid-scenario `When I save the current video as "name.webm"` overrides the
21
+ template for that scenario.
22
+
23
+ ## What is gitignored
24
+
25
+ Everything except this README. `.gitignore` keeps `videos/*.webm` out of
26
+ the repo so binary recordings do not bloat history. Share via your CI
27
+ artefact store or attach to a PR description directly.
28
+
29
+ ## Step reference
30
+
31
+ See `docs/04-step-reference.md` → "Video recording" for the full step
32
+ list and mode matrix.
package/.travis-ci.yml DELETED
@@ -1,16 +0,0 @@
1
- language: node_js
2
-
3
- node_js:
4
- - "20"
5
-
6
- before_script:
7
- - npm install
8
- - npx playwright install --with-deps chromium
9
-
10
- script:
11
- - npm start &
12
- - npm test
13
-
14
- cache:
15
- directories:
16
- - node_modules
package/docs/index.md DELETED
@@ -1,104 +0,0 @@
1
- # Webship-js Documentation
2
-
3
- Webship-js is a BDD-first browser-automation harness built on Playwright + Cucumber-js. Feature files in plain Gherkin; selectors that survive redesigns; smart waits that never sleep.
4
-
5
- ## Reading order
6
-
7
- ### Webship-js essentials (custom)
8
-
9
- | Doc | Topic |
10
- | --- | --- |
11
- | [00 Quick start](00-quick-start.md) | 5-minute path for newcomers |
12
- | [01 Getting started](01-getting-started.md) | Install, project layout, run modes |
13
- | [02 BBR smart waits](02-bbr-smart-waits.md) | Why we never `sleep N seconds` |
14
- | [03 Selector registry](03-selector-registry.md) | Named selectors + CMS / framework presets |
15
- | [04 Step reference](04-step-reference.md) | Every built-in step, by topic |
16
- | [05 Web-first assertions](05-web-first-assertions.md) | Auto-retrying matchers |
17
- | [06 Networking & dialogs](06-network-and-dialogs.md) | Request mocking, alerts, prompts |
18
- | [07 Auth state](07-auth-state.md) | Save / restore login |
19
- | [08 Clock mocking](08-clock-mocking.md) | Control time |
20
- | [09 API testing](09-api-testing.md) | Direct HTTP from BDD |
21
- | [10 Accessibility](10-accessibility.md) | POUR smoke checks |
22
- | [11 Debugging](11-debugging.md) | Screenshots, headed, traces, reports |
23
- | [12 AI agent guide](12-ai-agent-guide.md) | Wisdom + recipes from the Recipes book v1.0.30 (TDD AI / SPDD / Three Amigos / golden rules) |
24
- | [13 FAQ](13-faq.md) | Common questions for newcomers |
25
- | [14 Recipes cookbook](14-recipes-cookbook.md) | 20 paste-and-go scenarios |
26
- | [15 Tag conventions](15-tag-conventions.md) | Standard tags + CI lane patterns |
27
-
28
- ### Reference (mirrored from webship.co/docs/webship-js/2.0.x)
29
-
30
- | Doc | Topic |
31
- | --- | --- |
32
- | [Overview](overview.md) | Webship-js v2.0.x at a glance |
33
- | [Install](install-webship-js.md) | Install Webship-js |
34
- | [Install — DDEV](install-webship-js/ddev-webship-js.md) | DDEV-Webship-js variant |
35
- | [Global settings](global-settings.md) | `cucumber.js` `worldParameters` reference |
36
- | [Commands](commands.md) | CLI commands |
37
- | [Assertions](assertions.md) | Built-in assertions |
38
- | [Step definitions](step-definitions.md) | Step-definition catalogue (28 sub-pages under `step-definitions/`) |
39
- | [API step definitions](api-step-definitions.md) | REST step definitions |
40
- | [Advanced screenshots](advanced-screenshots.md) | Per-size, full-page, named (3 sub-pages under `advanced-screenshots/`) |
41
- | [Advanced selectors](advanced-selectors.md) | Named selector registry, position assertions |
42
- | [Diffy step definitions](diffy-step-definitions.md) | Visual-diff workflow (10 sub-pages under `diffy-step-definitions/`) |
43
-
44
- ## At a glance
45
-
46
- ```gherkin
47
- Feature: Smoke
48
-
49
- Background:
50
- Given I restore the auth state from "tests/auth/admin.json"
51
-
52
- @javascript
53
- Scenario: Dashboard renders without JS errors
54
- Given I am on "/dashboard"
55
- And I wait until the network is idle
56
- Then the page should have a main landmark
57
- And "<#user-list>" should have a count of 5 within 5 seconds
58
- And "<.notification>" should not be visible
59
- ```
60
-
61
- ## Source layout
62
-
63
- ```
64
- webship-js/
65
- ├── docs/ <— You are here
66
- ├── tests/
67
- │ ├── features/ <— Your *.feature files
68
- │ ├── selectors/ <— CMS / framework JSON presets
69
- │ └── step-definitions/ <— Built-in steps (auto-loaded)
70
- │ ├── webship.js # World setup, hooks, shared helpers (smartSettle, modal, selectors)
71
- │ ├── navigation.steps.js # homepage / paths / history / URL assertions
72
- │ ├── action.steps.js # press, click, follow, attach
73
- │ ├── form.steps.js # fill, select, check, radio
74
- │ ├── assertion.steps.js # see / not see, in row, in element, response, count
75
- │ ├── api.steps.js # REST API steps
76
- │ ├── screenshot.steps.js # Screenshot hooks
77
- │ ├── selectors.steps.js # Named selector registry
78
- │ ├── wait.steps.js # All wait phrasings (BBR)
79
- │ ├── web-first.steps.js # Auto-retrying matchers
80
- │ ├── auth.steps.js # Auth state save/restore
81
- │ ├── clock.steps.js # Time mocking
82
- │ ├── network.steps.js # Route stubs / blocks / delays
83
- │ ├── dialog.steps.js # alert/confirm/prompt
84
- │ ├── a11y.steps.js # Accessibility smoke checks
85
- │ ├── javascript.steps.js # JS error tracking
86
- │ ├── element.steps.js # Element interactions
87
- │ ├── field.steps.js # Form field assertions
88
- │ ├── cookie.steps.js # Cookie helpers
89
- │ ├── modal.steps.js # Modal helpers
90
- │ ├── keyboard.steps.js # Key press steps
91
- │ ├── link.steps.js # Link assertions
92
- │ ├── path.steps.js # URL path assertions
93
- │ ├── response.steps.js # Response header inspection
94
- │ ├── responsive.steps.js # Viewport breakpoints
95
- │ ├── table.steps.js # Table assertions
96
- │ ├── metatag.steps.js # <meta> assertions
97
- │ ├── iframe.steps.js # Iframe context steps
98
- │ ├── file-download.steps.js # Download capture
99
- │ ├── rest.steps.js # REST helpers
100
- │ └── xml.steps.js # XML body assertions
101
- ├── examples/ <— Static HTML fixtures
102
- ├── cucumber.js <— Profiles + worldParameters
103
- └── playwright.config.ts <— Browser launch + context options
104
- ```