webship-js 2.0.1 → 2.0.3

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 (194) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +363 -0
  4. package/bin/init-webship.js +343 -0
  5. package/bin/postinstall.js +8 -74
  6. package/cucumber.js +66 -2
  7. package/docs/00-quick-start.md +102 -0
  8. package/docs/01-getting-started.md +102 -0
  9. package/docs/02-bbr-smart-waits.md +77 -0
  10. package/docs/03-selector-registry.md +95 -0
  11. package/docs/04-step-reference.md +728 -0
  12. package/docs/05-web-first-assertions.md +91 -0
  13. package/docs/06-network-and-dialogs.md +83 -0
  14. package/docs/07-auth-state.md +75 -0
  15. package/docs/08-clock-mocking.md +59 -0
  16. package/docs/09-api-testing.md +114 -0
  17. package/docs/10-accessibility.md +167 -0
  18. package/docs/11-debugging.md +129 -0
  19. package/docs/12-ai-agent-guide.md +338 -0
  20. package/docs/13-faq.md +236 -0
  21. package/docs/14-recipes-cookbook.md +255 -0
  22. package/docs/15-tag-conventions.md +76 -0
  23. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  24. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  25. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  26. package/docs/advanced-screenshots.md +52 -0
  27. package/docs/advanced-selectors.md +18 -0
  28. package/docs/api-step-definitions.md +45 -0
  29. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  31. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  32. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  33. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  34. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  35. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  36. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  37. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  38. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  39. package/docs/diffy-step-definitions.md +21 -0
  40. package/docs/global-settings.md +244 -0
  41. package/docs/index.md +104 -0
  42. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  43. package/docs/install-webship-js.md +35 -0
  44. package/docs/overview.md +41 -0
  45. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  46. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  47. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  48. package/docs/step-definitions/then-i-should-be.md +56 -0
  49. package/docs/step-definitions/then-i-should-see.md +62 -0
  50. package/docs/step-definitions/then-item-checkbox.md +54 -0
  51. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  52. package/docs/step-definitions/then-item-should-contain.md +67 -0
  53. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  54. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  55. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  56. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  57. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  58. package/docs/step-definitions/when-i-click-link.md +51 -0
  59. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  60. package/docs/step-definitions/when-i-fill.md +59 -0
  61. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  62. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  63. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  64. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  65. package/docs/step-definitions/when-i-press-button.md +58 -0
  66. package/docs/step-definitions/when-i-reload-page.md +51 -0
  67. package/docs/step-definitions/when-i-scroll.md +73 -0
  68. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  69. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  70. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  71. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  72. package/docs/step-definitions/when-i-wait.md +62 -0
  73. package/docs/step-definitions.md +50 -0
  74. package/examples/a11y.html +31 -0
  75. package/examples/cookies.html +10 -0
  76. package/examples/date.html +12 -0
  77. package/examples/diffy/baseline.html +54 -0
  78. package/examples/diffy/changed.html +63 -0
  79. package/examples/diffy/index.html +52 -0
  80. package/examples/element.html +11 -0
  81. package/examples/field.html +24 -0
  82. package/examples/index.html +6 -0
  83. package/examples/keyboard.html +11 -0
  84. package/examples/links.html +9 -0
  85. package/examples/modal.html +14 -0
  86. package/examples/path.html +3 -0
  87. package/examples/table.html +13 -0
  88. package/examples/test--when--i-additionally-select.html +27 -0
  89. package/package.json +19 -6
  90. package/playwright.config.ts +3 -2
  91. package/tests/features/a11y.feature +39 -0
  92. package/tests/features/cookie.feature +13 -0
  93. package/tests/features/date.feature +11 -0
  94. package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
  95. package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
  96. package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
  97. package/tests/features/element.feature +16 -0
  98. package/tests/features/field.feature +25 -0
  99. package/tests/features/keyboard.feature +10 -0
  100. package/tests/features/link.feature +11 -0
  101. package/tests/features/modal-advanced-example.feature +1 -1
  102. package/tests/features/modal.feature +11 -0
  103. package/tests/features/path.feature +16 -0
  104. package/tests/features/response.feature +8 -0
  105. package/tests/features/responsive.feature +10 -0
  106. package/tests/features/table.feature +18 -0
  107. package/tests/features/test--then--i-save-screenshot.feature +33 -0
  108. package/tests/features/test--then--i-see-locator.feature +320 -0
  109. package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
  110. package/tests/features/test--then--print-current-url-and-response.feature +21 -0
  111. package/tests/features/test--when--i-additionally-select.feature +30 -0
  112. package/tests/features/test--when--i-follow.feature +22 -0
  113. package/tests/features/wait.feature +7 -0
  114. package/tests/features/yaml.feature +102 -0
  115. package/tests/reports/README.md +55 -0
  116. package/tests/selectors/_canonical-keys.json +113 -0
  117. package/tests/selectors/back-end-selectors.json +19 -0
  118. package/tests/selectors/cms-contentful-admin.json +35 -0
  119. package/tests/selectors/cms-craft-admin.json +39 -0
  120. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  121. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  122. package/tests/selectors/cms-generic-admin.json +34 -0
  123. package/tests/selectors/cms-ghost-admin.json +34 -0
  124. package/tests/selectors/cms-joomla-admin.json +41 -0
  125. package/tests/selectors/cms-magento2-admin.json +32 -0
  126. package/tests/selectors/cms-prestashop-admin.json +38 -0
  127. package/tests/selectors/cms-shopify-admin.json +25 -0
  128. package/tests/selectors/cms-strapi-admin.json +42 -0
  129. package/tests/selectors/cms-typo3-admin.json +41 -0
  130. package/tests/selectors/cms-woocommerce-front.json +50 -0
  131. package/tests/selectors/cms-wordpress-admin.json +31 -0
  132. package/tests/selectors/framework-ant-design.json +80 -0
  133. package/tests/selectors/framework-bootstrap.json +86 -0
  134. package/tests/selectors/framework-bulma.json +74 -0
  135. package/tests/selectors/framework-chakra.json +58 -0
  136. package/tests/selectors/framework-foundation.json +51 -0
  137. package/tests/selectors/framework-material-ui.json +72 -0
  138. package/tests/selectors/framework-shadcn.json +51 -0
  139. package/tests/selectors/framework-tailwind.json +40 -0
  140. package/tests/selectors/framework-vuetify.json +61 -0
  141. package/tests/selectors/front-end-selectors.json +16 -0
  142. package/tests/selectors/homepage-selectors.json +13 -0
  143. package/tests/step-definitions/a11y.steps.js +798 -0
  144. package/tests/step-definitions/action.steps.js +167 -0
  145. package/tests/step-definitions/{webship-api.js → api.steps.js} +254 -44
  146. package/tests/step-definitions/assertion.steps.js +352 -0
  147. package/tests/step-definitions/auth.steps.js +124 -0
  148. package/tests/step-definitions/clock.steps.js +128 -0
  149. package/tests/step-definitions/cookie.steps.js +216 -0
  150. package/tests/step-definitions/debug.steps.js +31 -0
  151. package/tests/step-definitions/dialog.steps.js +193 -0
  152. package/tests/step-definitions/element.steps.js +314 -0
  153. package/tests/step-definitions/field.steps.js +653 -0
  154. package/tests/step-definitions/file-download.steps.js +193 -0
  155. package/tests/step-definitions/form.steps.js +333 -0
  156. package/tests/step-definitions/iframe.steps.js +178 -0
  157. package/tests/step-definitions/input.steps.js +163 -0
  158. package/tests/step-definitions/javascript.steps.js +71 -0
  159. package/tests/step-definitions/keyboard.steps.js +78 -0
  160. package/tests/step-definitions/link.steps.js +142 -0
  161. package/tests/step-definitions/metatag.steps.js +91 -0
  162. package/tests/step-definitions/modal.steps.js +219 -0
  163. package/tests/step-definitions/navigation.steps.js +218 -0
  164. package/tests/step-definitions/network.steps.js +238 -0
  165. package/tests/step-definitions/path.steps.js +141 -0
  166. package/tests/step-definitions/response.steps.js +98 -0
  167. package/tests/step-definitions/responsive.steps.js +123 -0
  168. package/tests/step-definitions/rest.steps.js +111 -0
  169. package/tests/step-definitions/screenshot.steps.js +423 -0
  170. package/tests/step-definitions/scroll.steps.js +189 -0
  171. package/tests/step-definitions/selectors.steps.js +996 -0
  172. package/tests/step-definitions/storage.steps.js +194 -0
  173. package/tests/step-definitions/table.steps.js +181 -0
  174. package/tests/step-definitions/wait.steps.js +400 -0
  175. package/tests/step-definitions/web-first.steps.js +296 -0
  176. package/tests/step-definitions/webship.js +567 -923
  177. package/tests/step-definitions/xml.steps.js +409 -0
  178. package/tests/step-definitions/yaml.steps.js +911 -0
  179. package/tests/step-definitions-diffy/README.md +329 -0
  180. package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
  181. package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
  182. package/tests/step-definitions-diffy/webship-diffy.js +459 -0
  183. package/tsconfig.json +19 -3
  184. package/generate-reports.js +0 -22
  185. package/required/cucumber.js +0 -37
  186. package/required/generate-reports.js +0 -22
  187. package/required/package.json +0 -18
  188. package/required/playwright.config.ts +0 -37
  189. package/required/tests/features/README.md +0 -1
  190. package/required/tests/features/check-homepage.feature +0 -8
  191. package/required/tests/reports/README.md +0 -1
  192. package/required/tests/step-definitions/README.md +0 -1
  193. package/required/tests/step-definitions/custom.js +0 -4
  194. package/required/tsconfig.json +0 -12
@@ -0,0 +1,343 @@
1
+ #!/usr/bin/env node
2
+
3
+ 'use strict';
4
+
5
+ const fs = require('fs');
6
+ const path = require('path');
7
+ const { spawnSync } = require('child_process');
8
+
9
+ const packagePath = path.join(__dirname, '..');
10
+
11
+ const CUCUMBER_JS = `module.exports = {
12
+ default: {
13
+ timeout: 30000,
14
+ requireModule: ['ts-node/register'],
15
+ require: [
16
+ 'node_modules/webship-js/tests/step-definitions/**/*.js', // Webship-js core step definitions (auto HTML report on exit; disable: WEBSHIP_REPORT_DISABLE=1).
17
+ // 'node_modules/webship-js/tests/step-definitions-diffy/**/*.js', // Diffy step definitions (optional).
18
+ 'tests/step-definitions/**/*.js', // Your custom step definitions.
19
+ ],
20
+ paths: ['tests/features/**/*.feature'],
21
+ format: [
22
+ '@cucumber/pretty-formatter',
23
+ 'json:tests/reports/cucumber_report.json',
24
+ ],
25
+ formatOptions: {
26
+ colorsEnabled: true,
27
+ theme: {
28
+ 'feature keyword': ['bold', 'blue'],
29
+ 'feature name': ['blue', 'underline'],
30
+ 'feature description': ['blueBright'],
31
+ 'scenario keyword': ['bold', 'magenta'],
32
+ 'scenario name': ['magenta', 'underline'],
33
+ 'step keyword': ['bold', 'green'],
34
+ 'step text': ['greenBright', 'italic'],
35
+ },
36
+ },
37
+ worldParameters: {
38
+ launchUrl: process.env.LAUNCH_URL || 'http://localhost:8080',
39
+ minWaitTime: {
40
+ page: 3000,
41
+ before_scenario: 0,
42
+ after_scenario: 0,
43
+ before_step: 0,
44
+ after_step: 0,
45
+ },
46
+ selectors: {
47
+ css: {},
48
+ xpath: {},
49
+ filesPath: './tests/selectors/',
50
+ files: [],
51
+ offset: 60,
52
+ breakpoints: {
53
+ xs: { width: 375, height: 667 },
54
+ sm: { width: 576, height: 800 },
55
+ md: { width: 768, height: 1024 },
56
+ lg: { width: 992, height: 768 },
57
+ xl: { width: 1200, height: 900, default: true },
58
+ xxl: { width: 1400, height: 900 },
59
+ xxxl: { width: 1920, height: 1080 },
60
+ },
61
+ },
62
+ screenshot: {
63
+ dir: './screenshots',
64
+ purge: false,
65
+ onFailed: true,
66
+ onEveryStep: false,
67
+ alwaysFullscreen: false,
68
+ failedPrefix: 'failed_',
69
+ filenamePattern: '{datetime}.{feature_file}.feature_{step_line}.{ext}',
70
+ filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}',
71
+ infoTypes: '',
72
+ },
73
+ // Diffy visual-regression (optional). Uncomment and set apiKey / projectId to enable.
74
+ // diffy: {
75
+ // apiKey: '', // DIFFY_API_KEY
76
+ // projectId: 0, // DIFFY_PROJECT_ID
77
+ // breakpoints: '640,1200', // DIFFY_BREAKPOINTS
78
+ // windowHeight: 2000, // DIFFY_WINDOW_HEIGHT
79
+ // screenshotsDir: '', // DIFFY_SCREENSHOTS_DIR
80
+ // baseUrl: 'https://app.diffy.website/api/', // DIFFY_API_BASE_URL
81
+ // maxWait: 30, // DIFFY_MAX_WAIT (seconds)
82
+ // env1Url: '', // DIFFY_ENV1_URL
83
+ // env2Url: '', // DIFFY_ENV2_URL
84
+ // },
85
+ },
86
+ },
87
+ };
88
+ `;
89
+
90
+ const PLAYWRIGHT_CONFIG_TS = `import type { LaunchOptions, BrowserContextOptions } from 'playwright';
91
+
92
+ type BrowserName = 'chromium' | 'firefox' | 'webkit';
93
+
94
+ const browser = (process.env.BROWSER || 'chromium') as BrowserName;
95
+
96
+ const chromiumArgs: string[] = [
97
+ '--no-sandbox',
98
+ '--disable-dev-shm-usage',
99
+ '--disable-setuid-sandbox',
100
+ '--disable-web-security',
101
+ '--ignore-certificate-errors',
102
+ '--disable-extensions',
103
+ '--incognito',
104
+ '--disable-infobars',
105
+ ];
106
+
107
+ interface PlaywrightConfig {
108
+ browser: BrowserName;
109
+ launchOptions: LaunchOptions;
110
+ contextOptions: BrowserContextOptions;
111
+ }
112
+
113
+ const config: PlaywrightConfig = {
114
+ browser,
115
+ launchOptions: {
116
+ headless: true,
117
+ slowMo: 300,
118
+ args: browser === 'chromium' ? chromiumArgs : [],
119
+ },
120
+ contextOptions: {
121
+ viewport: { width: 1600, height: 1200 },
122
+ ignoreHTTPSErrors: true,
123
+ },
124
+ };
125
+
126
+ export = config;
127
+ `;
128
+
129
+ const TSCONFIG_JSON = {
130
+ compilerOptions: {
131
+ target: 'ES2020',
132
+ module: 'CommonJS',
133
+ strict: true,
134
+ esModuleInterop: true,
135
+ types: ['node'],
136
+ },
137
+ 'ts-node': {
138
+ ignore: ['node_modules/(?!webship-js/)'],
139
+ },
140
+ };
141
+
142
+ const FEATURE_SAMPLE = `Feature: Check the home page
143
+ As a nonymouse user
144
+ I want to be able to visit the home page
145
+ So that I know that the site is working
146
+
147
+ Scenario: Check homepage
148
+ Given I am on the homepage
149
+ Then I should see "Love to help in speeding up the work of having Automated Functional Acceptance Testing for products to ship websites in a swift way."
150
+ `;
151
+
152
+ const CUSTOM_STEP_JS = `const { Given, When, Then } = require('@cucumber/cucumber');
153
+ const playwrightConfig = require(require('path').join(process.cwd(), 'playwright.config'));
154
+
155
+ // Add your custom step definitions here.
156
+ `;
157
+
158
+ const TEXT_ASSETS = {
159
+ 'cucumber.js': CUCUMBER_JS,
160
+ 'playwright.config.ts': PLAYWRIGHT_CONFIG_TS,
161
+ 'tests/features/README.md': '# Features\n',
162
+ 'tests/features/check-homepage.feature': FEATURE_SAMPLE,
163
+ 'tests/reports/README.md': '# Reports\n',
164
+ 'tests/step-definitions/README.md': '# Step Definitions\n',
165
+ 'tests/step-definitions/custom.js': CUSTOM_STEP_JS,
166
+ };
167
+
168
+ const TEST_SCRIPTS = {
169
+ test: 'cucumber-js --config cucumber.js',
170
+ 'test:chromium': 'BROWSER=chromium cucumber-js --config cucumber.js',
171
+ 'test:firefox': 'BROWSER=firefox cucumber-js --config cucumber.js',
172
+ 'test:webkit': 'BROWSER=webkit cucumber-js --config cucumber.js',
173
+ 'generate-reports': 'generate-reports',
174
+ };
175
+
176
+ const DEFAULT_PKG = {
177
+ name: 'project-name',
178
+ version: '2.0.0',
179
+ description: '',
180
+ main: 'index.js',
181
+ author: '',
182
+ license: 'MIT',
183
+ private: false,
184
+ scripts: {},
185
+ homepage: 'https://github.com/webship/webship-js',
186
+ dependencies: {},
187
+ };
188
+
189
+ function parseArgs(argv) {
190
+ const opts = { force: false, skipBrowsers: false, help: false, cwd: null };
191
+ for (let i = 0; i < argv.length; i++) {
192
+ const a = argv[i];
193
+ if (a === '--force' || a === '-f') opts.force = true;
194
+ else if (a === '--skip-browsers') opts.skipBrowsers = true;
195
+ else if (a === '--help' || a === '-h') opts.help = true;
196
+ else if (a === '--cwd') opts.cwd = argv[++i];
197
+ }
198
+ return opts;
199
+ }
200
+
201
+ function printHelp() {
202
+ process.stdout.write(
203
+ [
204
+ 'Usage: init-webship-js [options]',
205
+ '',
206
+ 'Scaffold a webship-js project: cucumber.js, playwright.config.ts,',
207
+ 'tsconfig.json, tests/ tree, and package.json scripts.',
208
+ 'Idempotent — safe to run multiple times.',
209
+ '',
210
+ 'Options:',
211
+ ' -f, --force Overwrite existing files',
212
+ ' --skip-browsers Skip `playwright install chromium`',
213
+ ' --cwd <dir> Target directory (default: $INIT_CWD or cwd)',
214
+ ' -h, --help Show this help',
215
+ '',
216
+ ].join('\n')
217
+ );
218
+ }
219
+
220
+ function writeFileIfMissing(destPath, content, { force }) {
221
+ if (!force && fs.existsSync(destPath)) return false;
222
+ fs.mkdirSync(path.dirname(destPath), { recursive: true });
223
+ fs.writeFileSync(destPath, content, 'utf8');
224
+ return true;
225
+ }
226
+
227
+ function ensureDir(dir) {
228
+ fs.mkdirSync(dir, { recursive: true });
229
+ }
230
+
231
+ function readPkgVersion() {
232
+ try {
233
+ const pkg = JSON.parse(
234
+ fs.readFileSync(path.join(packagePath, 'package.json'), 'utf8')
235
+ );
236
+ const major = String(pkg.version).split('.')[0] || '2';
237
+ return `~${major}.0.0`;
238
+ } catch {
239
+ return '~2.0.0';
240
+ }
241
+ }
242
+
243
+ function writeTextAssets(projectPath, opts) {
244
+ const results = [];
245
+ for (const [rel, content] of Object.entries(TEXT_ASSETS)) {
246
+ const dest = path.join(projectPath, rel);
247
+ const written = writeFileIfMissing(dest, content, opts);
248
+ results.push({ file: rel, written });
249
+ }
250
+ return results;
251
+ }
252
+
253
+ function writeTsconfig(projectPath, opts) {
254
+ const dest = path.join(projectPath, 'tsconfig.json');
255
+ if (!opts.force && fs.existsSync(dest)) return false;
256
+ fs.writeFileSync(dest, JSON.stringify(TSCONFIG_JSON, null, 2) + '\n', 'utf8');
257
+ return true;
258
+ }
259
+
260
+ function ensurePackageJson(projectPath, opts) {
261
+ const pkgPath = path.join(projectPath, 'package.json');
262
+ const existed = fs.existsSync(pkgPath);
263
+
264
+ let pkg;
265
+ if (existed) {
266
+ pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
267
+ } else {
268
+ pkg = { ...DEFAULT_PKG };
269
+ }
270
+
271
+ pkg.scripts = pkg.scripts || {};
272
+ for (const [name, cmd] of Object.entries(TEST_SCRIPTS)) {
273
+ if (opts.force || !pkg.scripts[name]) {
274
+ pkg.scripts[name] = cmd;
275
+ }
276
+ }
277
+
278
+ pkg.dependencies = pkg.dependencies || {};
279
+ if (opts.force || !pkg.dependencies['webship-js']) {
280
+ pkg.dependencies['webship-js'] = readPkgVersion();
281
+ }
282
+
283
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
284
+ return { created: !existed };
285
+ }
286
+
287
+ function installBrowsers(projectPath) {
288
+ console.log('\n [webship-js] Installing Playwright browsers...\n');
289
+ const res = spawnSync(
290
+ 'npx',
291
+ ['playwright', 'install', '--with-deps', 'chromium'],
292
+ { cwd: projectPath, stdio: 'inherit', shell: true }
293
+ );
294
+ return res.status === 0;
295
+ }
296
+
297
+ function run(argv) {
298
+ const opts = parseArgs(argv);
299
+ if (opts.help) return printHelp();
300
+
301
+ const projectPath = path.resolve(
302
+ opts.cwd || process.env.INIT_CWD || process.cwd()
303
+ );
304
+
305
+ if (
306
+ projectPath === packagePath ||
307
+ projectPath.startsWith(path.join(packagePath, 'node_modules'))
308
+ ) {
309
+ console.log(' [webship-js] Skipping init inside webship-js itself.');
310
+ return;
311
+ }
312
+
313
+ console.log(`\n [webship-js] Initializing project at ${projectPath}\n`);
314
+
315
+ ensureDir(projectPath);
316
+ ensureDir(path.join(projectPath, 'tests', 'features'));
317
+ ensureDir(path.join(projectPath, 'tests', 'reports'));
318
+ ensureDir(path.join(projectPath, 'tests', 'step-definitions'));
319
+ ensureDir(path.join(projectPath, 'tests', 'selectors'));
320
+ ensureDir(path.join(projectPath, 'screenshots'));
321
+
322
+ const assetResults = writeTextAssets(projectPath, opts);
323
+ const tsconfigWritten = writeTsconfig(projectPath, opts);
324
+ const pkgResult = ensurePackageJson(projectPath, opts);
325
+
326
+ for (const r of assetResults) {
327
+ console.log(` [${r.written ? 'wrote ' : 'kept '}] ${r.file}`);
328
+ }
329
+ console.log(` [${tsconfigWritten ? 'wrote ' : 'kept '}] tsconfig.json`);
330
+ console.log(
331
+ ` [${pkgResult.created ? 'wrote ' : 'merged'}] package.json`
332
+ );
333
+
334
+ if (!opts.skipBrowsers) installBrowsers(projectPath);
335
+
336
+ console.log('\n [webship-js] Setup complete!\n');
337
+ }
338
+
339
+ if (require.main === module) {
340
+ run(process.argv.slice(2));
341
+ }
342
+
343
+ module.exports = { run };
@@ -4,15 +4,12 @@
4
4
 
5
5
  const fs = require('fs');
6
6
  const path = require('path');
7
- const { spawnSync } = require('child_process');
7
+ const { run } = require('./init-webship');
8
8
 
9
- // The directory where `npm install` was invoked (the user's project root)
10
- const projectPath = process.env.INIT_CWD || process.cwd();
11
-
12
- // The webship-js package directory
13
9
  const packagePath = path.join(__dirname, '..');
10
+ const projectPath = process.env.INIT_CWD || process.cwd();
14
11
 
15
- // Skip if running inside webship-js itself (e.g. during development or CI of webship-js)
12
+ // Skip when invoked from webship-js itself (development / CI).
16
13
  if (
17
14
  projectPath === packagePath ||
18
15
  projectPath.startsWith(path.join(packagePath, 'node_modules'))
@@ -20,73 +17,10 @@ if (
20
17
  process.exit(0);
21
18
  }
22
19
 
23
- // Path to required template files bundled with webship-js
24
- const requiredDir = path.join(packagePath, 'required');
25
-
26
- function copyDirSync(src, dest) {
27
- fs.mkdirSync(dest, { recursive: true });
28
- for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
29
- const srcPath = path.join(src, entry.name);
30
- const destPath = path.join(dest, entry.name);
31
- if (entry.isDirectory()) {
32
- copyDirSync(srcPath, destPath);
33
- } else {
34
- fs.copyFileSync(srcPath, destPath);
35
- }
36
- }
37
- }
38
-
39
- // Only copy template files on a fresh install (tests/ not yet present)
40
- const testsTarget = path.join(projectPath, 'tests');
41
- if (!fs.existsSync(testsTarget)) {
42
- console.log('\n [webship-js] Installing required files...\n');
43
-
44
- copyDirSync(path.join(requiredDir, 'tests'), testsTarget);
45
-
46
- fs.copyFileSync(
47
- path.join(requiredDir, 'generate-reports.js'),
48
- path.join(projectPath, 'generate-reports.js')
49
- );
50
-
51
- fs.copyFileSync(
52
- path.join(requiredDir, 'cucumber.js'),
53
- path.join(projectPath, 'cucumber.js')
54
- );
55
-
56
- fs.copyFileSync(
57
- path.join(requiredDir, 'tsconfig.json'),
58
- path.join(projectPath, 'tsconfig.json')
59
- );
60
-
61
- fs.copyFileSync(
62
- path.join(requiredDir, 'playwright.config.ts'),
63
- path.join(projectPath, 'playwright.config.ts')
64
- );
65
-
66
- // Only copy package.json if the project does not have one yet
67
- const targetPkgJson = path.join(projectPath, 'package.json');
68
- if (!fs.existsSync(targetPkgJson)) {
69
- fs.copyFileSync(path.join(requiredDir, 'package.json'), targetPkgJson);
70
- }
71
- }
72
-
73
- // Always ensure the test scripts are present in package.json
74
- const targetPkgJson = path.join(projectPath, 'package.json');
75
- if (fs.existsSync(targetPkgJson)) {
76
- const pkgJson = JSON.parse(fs.readFileSync(targetPkgJson, 'utf8'));
77
- pkgJson.scripts = pkgJson.scripts || {};
78
- pkgJson.scripts.test = 'cucumber-js --config cucumber.js; node generate-reports.js;';
79
- pkgJson.scripts['test:firefox'] = 'BROWSER=firefox cucumber-js --config cucumber.js; node generate-reports.js;';
80
- pkgJson.scripts['test:webkit'] = 'BROWSER=webkit cucumber-js --config cucumber.js; node generate-reports.js;';
81
- fs.writeFileSync(targetPkgJson, JSON.stringify(pkgJson, null, 2) + '\n', 'utf8');
20
+ // Only run on a fresh project — cucumber.js absence marks an uninitialized project.
21
+ // Re-installs (npm install, npm ci) will not overwrite user customizations.
22
+ if (fs.existsSync(path.join(projectPath, 'cucumber.js'))) {
23
+ process.exit(0);
82
24
  }
83
25
 
84
- // Install Playwright browsers
85
- console.log('\n [webship-js] Installing Playwright browsers...\n');
86
- spawnSync('npx', ['playwright', 'install', '--with-deps', 'chromium'], {
87
- cwd: projectPath,
88
- stdio: 'inherit',
89
- shell: true,
90
- });
91
-
92
- console.log('\n [webship-js] Setup complete!\n');
26
+ run(['--cwd', projectPath]);
package/cucumber.js CHANGED
@@ -1,9 +1,15 @@
1
1
  module.exports = {
2
2
  default: {
3
3
  timeout: 30000,
4
- requireModule: ['ts-node/register'],
4
+ // tsx/cjs registers a require() hook so cucumber-js can load both
5
+ // `.js` and `.ts` step files with zero build step. If you ship only
6
+ // JavaScript, drop `requireModule` and the `.ts` half of the glob.
7
+ requireModule: ['tsx/cjs'],
5
8
  require: [
6
9
  'tests/step-definitions/**/*.js',
10
+ 'tests/step-definitions/**/*.ts',
11
+ 'tests/step-definitions-diffy/**/*.js',
12
+ 'tests/step-definitions-diffy/**/*.ts',
7
13
  ],
8
14
  paths: ['tests/features/**/*.feature'],
9
15
  format: [
@@ -11,7 +17,8 @@ module.exports = {
11
17
  'json:tests/reports/cucumber_report.json',
12
18
  ],
13
19
  formatOptions: {
14
- colorsEnabled: true,
20
+ // Color toggle is controlled via the FORCE_COLOR env var (per
21
+ // cucumber-js v10+); the deprecated `colorsEnabled` option is gone.
15
22
  theme: {
16
23
  'feature keyword': ['bold', 'blue'],
17
24
  'feature name': ['blue', 'underline'],
@@ -31,6 +38,63 @@ module.exports = {
31
38
  before_step: 0,
32
39
  after_step: 0,
33
40
  },
41
+ selectors: {
42
+ // Named CSS selectors — layout components and element locators in one registry.
43
+ // Register inline: When I add "name" selector for "css" css selector
44
+ // Or in bulk: Given I define css selectors:
45
+ // | name | css selector |
46
+ css: {
47
+ // 'header': 'header.page-header',
48
+ // 'main nav': 'nav[role="navigation"]',
49
+ // 'breadcrumb': '.breadcrumb',
50
+ // 'breadcrumb first link': '.breadcrumb li:nth-child(1) a',
51
+ // 'message': '.messages',
52
+ // 'error message': '.messages.error',
53
+ // 'success message': '.messages.status',
54
+ // 'warning message': '.messages.warning',
55
+ },
56
+ // Named XPath selectors — use with: When I add "name" selector for "xpath" xpath selector
57
+ xpath: {
58
+ // 'page title': '//h1[contains(@class,"page-header")]',
59
+ },
60
+ // Load additional selectors from JSON files at scenario start.
61
+ filesPath: './tests/selectors/', // base path for selector files
62
+ files: [], // e.g. ['homepage-selectors.json'] or ['front-end-selectors.json', 'back-end-selectors.json']
63
+ // Relative-position scroll offset (px) — WEBSHIP_SELECTORS_OFFSET
64
+ offset: 60,
65
+ // Viewport breakpoints — WEBSHIP_SELECTORS_BREAKPOINTS (JSON string)
66
+ breakpoints: {
67
+ xs: { width: 375, height: 667 }, // phone portrait
68
+ sm: { width: 576, height: 800 }, // large phone / phablet
69
+ md: { width: 768, height: 1024 }, // tablet portrait
70
+ lg: { width: 992, height: 768 }, // small laptop / tablet landscape
71
+ xl: { width: 1200, height: 900, default: true }, // desktop
72
+ xxl: { width: 1400, height: 900 }, // wide desktop / HD
73
+ xxxl: { width: 1920, height: 1080 }, // Full HD / large monitor
74
+ },
75
+ },
76
+ screenshot: {
77
+ dir: './screenshots', // WEBSHIP_SCREENSHOT_DIR
78
+ purge: false, // WEBSHIP_SCREENSHOT_PURGE
79
+ onFailed: true, // WEBSHIP_SCREENSHOT_ON_FAILED
80
+ onEveryStep: false, // WEBSHIP_SCREENSHOT_ON_EVERY_STEP
81
+ alwaysFullscreen: false, // WEBSHIP_SCREENSHOT_FULLSCREEN
82
+ failedPrefix: 'failed_', // WEBSHIP_SCREENSHOT_FAILED_PREFIX
83
+ filenamePattern: '{datetime}.{feature_file}.feature_{step_line}.{ext}', // WEBSHIP_SCREENSHOT_PATTERN
84
+ filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}', // WEBSHIP_SCREENSHOT_PATTERN_FAIL
85
+ infoTypes: '', // WEBSHIP_SCREENSHOT_INFO_TYPES e.g. "url,feature,step,datetime"
86
+ },
87
+ diffy: {
88
+ apiKey: 'mock-key', // DIFFY_API_KEY
89
+ projectId: 1, // DIFFY_PROJECT_ID
90
+ breakpoints: '640,1200', // DIFFY_BREAKPOINTS
91
+ windowHeight: 2000, // DIFFY_WINDOW_HEIGHT
92
+ screenshotsDir: '', // DIFFY_SCREENSHOTS_DIR
93
+ baseUrl: 'http://127.0.0.1:3099/', // DIFFY_API_BASE_URL (mock server)
94
+ maxWait: 30, // DIFFY_MAX_WAIT (seconds)
95
+ env1Url: '', // DIFFY_ENV1_URL (custom env)
96
+ env2Url: '', // DIFFY_ENV2_URL (custom env)
97
+ },
34
98
  },
35
99
  },
36
100
  };
@@ -0,0 +1,102 @@
1
+ # Quick Start (5 minutes)
2
+
3
+ Brand new to webship-js? Read this page once. You'll be writing tests in
4
+ five minutes.
5
+
6
+ ## What you write
7
+
8
+ Plain English scenarios. No JavaScript required.
9
+
10
+ ```gherkin
11
+ Feature: Sign in
12
+
13
+ Scenario: Successful login
14
+ Given I am on "/login"
15
+ When I fill in "Email" with "alice@example.com"
16
+ And I fill in "Password" with "s3cret"
17
+ And I press "Sign in"
18
+ Then I should see "Welcome, Alice"
19
+ ```
20
+
21
+ That's a complete test. Every line maps to a built-in step. No setup
22
+ code. No selector jargon.
23
+
24
+ ## What you get
25
+
26
+ * **Real browser** — runs in Chromium, Firefox, or WebKit via Playwright.
27
+ * **Automatic smart waits** — every action waits for the page to
28
+ settle. No `sleep` / `wait 5s` needed in the happy path.
29
+ * **HTML report** — runs auto-generate `tests/reports/cucumber_report.html`.
30
+ * **Screenshots on failure** — saved to `screenshots/` for instant
31
+ debugging.
32
+
33
+ ## 30-second install
34
+
35
+ ```bash
36
+ npm install webship-js --save-dev
37
+ ```
38
+
39
+ The post-install script copies a starter `cucumber.js`,
40
+ `playwright.config.ts`, and `tests/` skeleton.
41
+
42
+ ## 60-second first test
43
+
44
+ 1. Drop your scenario into `tests/features/smoke.feature`.
45
+ 2. Make sure your dev server is running on `http://localhost:8080`
46
+ (or set `LAUNCH_URL` to point elsewhere).
47
+ 3. Run:
48
+
49
+ ```bash
50
+ npm test
51
+ ```
52
+
53
+ If your scenario passes, you're done. If it fails, the Cucumber output
54
+ names the step that failed and the expected vs actual.
55
+
56
+ ## Where to go next
57
+
58
+ | Want to… | Read |
59
+ | --- | --- |
60
+ | Understand smart waits (no `sleep`) | [02 BBR smart waits](02-bbr-smart-waits.md) |
61
+ | Use named selectors instead of long CSS | [03 Selector registry](03-selector-registry.md) |
62
+ | See every built-in step | [04 Step reference](04-step-reference.md) |
63
+ | Test forms / clicks / modals | [04 Step reference](04-step-reference.md) |
64
+ | Mock APIs / dialogs | [06 Networking & dialogs](06-network-and-dialogs.md) |
65
+ | Accessibility audits | [10 Accessibility](10-accessibility.md) |
66
+ | Use AI to generate tests | [12 AI agent guide](12-ai-agent-guide.md) |
67
+ | FAQ | [13 FAQ](13-faq.md) |
68
+ | Recipes cookbook | [14 Recipes cookbook](14-recipes-cookbook.md) |
69
+
70
+ ## The mental model
71
+
72
+ * `Given` — set up the scene (navigate, restore auth, seed data).
73
+ * `When` — do something (click, fill, submit).
74
+ * `Then` — check what should be true (text visible, URL changed).
75
+ * `And` / `But` — continuation. Pick whichever reads naturally.
76
+ * `Background:` — steps shared across every scenario in a feature.
77
+ * `Scenario Outline:` + `Examples:` — same scenario with different data.
78
+
79
+ ## The golden rule
80
+
81
+ **Wait for events, not time.** Webship-js does this for you in the
82
+ common case. If you ever feel tempted to add `wait 5 seconds` because
83
+ something flaked, look for an event-based wait first:
84
+
85
+ ```gherkin
86
+ # Bad — slow, brittle.
87
+ When I press "Save"
88
+ And I wait 5 seconds
89
+ Then I should see "Saved"
90
+
91
+ # Good — instant when fast, patient when slow.
92
+ When I press "Save"
93
+ Then I should see "Saved"
94
+
95
+ # Best when "Save" navigates.
96
+ When I press "Save"
97
+ And I wait until the URL contains "/saved"
98
+ Then I should see "Saved"
99
+ ```
100
+
101
+ That's the entire philosophy. Read [02 BBR smart waits](02-bbr-smart-waits.md)
102
+ when you're ready to internalise the details.