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.
- package/AGENTS.md +109 -0
- package/CLAUDE.md +317 -0
- package/bin/generate-reports.js +363 -0
- package/bin/init-webship.js +343 -0
- package/bin/postinstall.js +8 -74
- package/cucumber.js +66 -2
- package/docs/00-quick-start.md +102 -0
- package/docs/01-getting-started.md +102 -0
- package/docs/02-bbr-smart-waits.md +77 -0
- package/docs/03-selector-registry.md +95 -0
- package/docs/04-step-reference.md +728 -0
- package/docs/05-web-first-assertions.md +91 -0
- package/docs/06-network-and-dialogs.md +83 -0
- package/docs/07-auth-state.md +75 -0
- package/docs/08-clock-mocking.md +59 -0
- package/docs/09-api-testing.md +114 -0
- package/docs/10-accessibility.md +167 -0
- package/docs/11-debugging.md +129 -0
- package/docs/12-ai-agent-guide.md +338 -0
- package/docs/13-faq.md +236 -0
- package/docs/14-recipes-cookbook.md +255 -0
- package/docs/15-tag-conventions.md +76 -0
- package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
- package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
- package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
- package/docs/advanced-screenshots.md +52 -0
- package/docs/advanced-selectors.md +18 -0
- package/docs/api-step-definitions.md +45 -0
- package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
- package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
- package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
- package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
- package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
- package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
- package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
- package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
- package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
- package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
- package/docs/diffy-step-definitions.md +21 -0
- package/docs/global-settings.md +244 -0
- package/docs/index.md +104 -0
- package/docs/install-webship-js/ddev-webship-js.md +52 -0
- package/docs/install-webship-js.md +35 -0
- package/docs/overview.md +41 -0
- package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
- package/docs/step-definitions/given-i-am-homepage.md +68 -0
- package/docs/step-definitions/given-i-am-specific-page.md +72 -0
- package/docs/step-definitions/then-i-should-be.md +56 -0
- package/docs/step-definitions/then-i-should-see.md +62 -0
- package/docs/step-definitions/then-item-checkbox.md +54 -0
- package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
- package/docs/step-definitions/then-item-should-contain.md +67 -0
- package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
- package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
- package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
- package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
- package/docs/step-definitions/when-i-check-checkbox.md +60 -0
- package/docs/step-definitions/when-i-click-link.md +51 -0
- package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
- package/docs/step-definitions/when-i-fill.md +59 -0
- package/docs/step-definitions/when-i-go-homepage.md +60 -0
- package/docs/step-definitions/when-i-go-specific-page.md +67 -0
- package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
- package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
- package/docs/step-definitions/when-i-press-button.md +58 -0
- package/docs/step-definitions/when-i-reload-page.md +51 -0
- package/docs/step-definitions/when-i-scroll.md +73 -0
- package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
- package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
- package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
- package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
- package/docs/step-definitions/when-i-wait.md +62 -0
- package/docs/step-definitions.md +50 -0
- package/examples/a11y.html +31 -0
- package/examples/cookies.html +10 -0
- package/examples/date.html +12 -0
- package/examples/diffy/baseline.html +54 -0
- package/examples/diffy/changed.html +63 -0
- package/examples/diffy/index.html +52 -0
- package/examples/element.html +11 -0
- package/examples/field.html +24 -0
- package/examples/index.html +6 -0
- package/examples/keyboard.html +11 -0
- package/examples/links.html +9 -0
- package/examples/modal.html +14 -0
- package/examples/path.html +3 -0
- package/examples/table.html +13 -0
- package/examples/test--when--i-additionally-select.html +27 -0
- package/package.json +19 -6
- package/playwright.config.ts +3 -2
- package/tests/features/a11y.feature +39 -0
- package/tests/features/cookie.feature +13 -0
- package/tests/features/date.feature +11 -0
- package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
- package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
- package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
- package/tests/features/element.feature +16 -0
- package/tests/features/field.feature +25 -0
- package/tests/features/keyboard.feature +10 -0
- package/tests/features/link.feature +11 -0
- package/tests/features/modal-advanced-example.feature +1 -1
- package/tests/features/modal.feature +11 -0
- package/tests/features/path.feature +16 -0
- package/tests/features/response.feature +8 -0
- package/tests/features/responsive.feature +10 -0
- package/tests/features/table.feature +18 -0
- package/tests/features/test--then--i-save-screenshot.feature +33 -0
- package/tests/features/test--then--i-see-locator.feature +320 -0
- package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
- package/tests/features/test--then--print-current-url-and-response.feature +21 -0
- package/tests/features/test--when--i-additionally-select.feature +30 -0
- package/tests/features/test--when--i-follow.feature +22 -0
- package/tests/features/wait.feature +7 -0
- package/tests/features/yaml.feature +102 -0
- package/tests/reports/README.md +55 -0
- package/tests/selectors/_canonical-keys.json +113 -0
- package/tests/selectors/back-end-selectors.json +19 -0
- package/tests/selectors/cms-contentful-admin.json +35 -0
- package/tests/selectors/cms-craft-admin.json +39 -0
- package/tests/selectors/cms-drupal-cms-gin.json +56 -0
- package/tests/selectors/cms-drupal-core-claro.json +50 -0
- package/tests/selectors/cms-generic-admin.json +34 -0
- package/tests/selectors/cms-ghost-admin.json +34 -0
- package/tests/selectors/cms-joomla-admin.json +41 -0
- package/tests/selectors/cms-magento2-admin.json +32 -0
- package/tests/selectors/cms-prestashop-admin.json +38 -0
- package/tests/selectors/cms-shopify-admin.json +25 -0
- package/tests/selectors/cms-strapi-admin.json +42 -0
- package/tests/selectors/cms-typo3-admin.json +41 -0
- package/tests/selectors/cms-woocommerce-front.json +50 -0
- package/tests/selectors/cms-wordpress-admin.json +31 -0
- package/tests/selectors/framework-ant-design.json +80 -0
- package/tests/selectors/framework-bootstrap.json +86 -0
- package/tests/selectors/framework-bulma.json +74 -0
- package/tests/selectors/framework-chakra.json +58 -0
- package/tests/selectors/framework-foundation.json +51 -0
- package/tests/selectors/framework-material-ui.json +72 -0
- package/tests/selectors/framework-shadcn.json +51 -0
- package/tests/selectors/framework-tailwind.json +40 -0
- package/tests/selectors/framework-vuetify.json +61 -0
- package/tests/selectors/front-end-selectors.json +16 -0
- package/tests/selectors/homepage-selectors.json +13 -0
- package/tests/step-definitions/a11y.steps.js +798 -0
- package/tests/step-definitions/action.steps.js +167 -0
- package/tests/step-definitions/{webship-api.js → api.steps.js} +254 -44
- package/tests/step-definitions/assertion.steps.js +352 -0
- package/tests/step-definitions/auth.steps.js +124 -0
- package/tests/step-definitions/clock.steps.js +128 -0
- package/tests/step-definitions/cookie.steps.js +216 -0
- package/tests/step-definitions/debug.steps.js +31 -0
- package/tests/step-definitions/dialog.steps.js +193 -0
- package/tests/step-definitions/element.steps.js +314 -0
- package/tests/step-definitions/field.steps.js +653 -0
- package/tests/step-definitions/file-download.steps.js +193 -0
- package/tests/step-definitions/form.steps.js +333 -0
- package/tests/step-definitions/iframe.steps.js +178 -0
- package/tests/step-definitions/input.steps.js +163 -0
- package/tests/step-definitions/javascript.steps.js +71 -0
- package/tests/step-definitions/keyboard.steps.js +78 -0
- package/tests/step-definitions/link.steps.js +142 -0
- package/tests/step-definitions/metatag.steps.js +91 -0
- package/tests/step-definitions/modal.steps.js +219 -0
- package/tests/step-definitions/navigation.steps.js +218 -0
- package/tests/step-definitions/network.steps.js +238 -0
- package/tests/step-definitions/path.steps.js +141 -0
- package/tests/step-definitions/response.steps.js +98 -0
- package/tests/step-definitions/responsive.steps.js +123 -0
- package/tests/step-definitions/rest.steps.js +111 -0
- package/tests/step-definitions/screenshot.steps.js +423 -0
- package/tests/step-definitions/scroll.steps.js +189 -0
- package/tests/step-definitions/selectors.steps.js +996 -0
- package/tests/step-definitions/storage.steps.js +194 -0
- package/tests/step-definitions/table.steps.js +181 -0
- package/tests/step-definitions/wait.steps.js +400 -0
- package/tests/step-definitions/web-first.steps.js +296 -0
- package/tests/step-definitions/webship.js +567 -923
- package/tests/step-definitions/xml.steps.js +409 -0
- package/tests/step-definitions/yaml.steps.js +911 -0
- package/tests/step-definitions-diffy/README.md +329 -0
- package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
- package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
- package/tests/step-definitions-diffy/webship-diffy.js +459 -0
- package/tsconfig.json +19 -3
- package/generate-reports.js +0 -22
- package/required/cucumber.js +0 -37
- package/required/generate-reports.js +0 -22
- package/required/package.json +0 -18
- package/required/playwright.config.ts +0 -37
- package/required/tests/features/README.md +0 -1
- package/required/tests/features/check-homepage.feature +0 -8
- package/required/tests/reports/README.md +0 -1
- package/required/tests/step-definitions/README.md +0 -1
- package/required/tests/step-definitions/custom.js +0 -4
- 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 };
|
package/bin/postinstall.js
CHANGED
|
@@ -4,15 +4,12 @@
|
|
|
4
4
|
|
|
5
5
|
const fs = require('fs');
|
|
6
6
|
const path = require('path');
|
|
7
|
-
const {
|
|
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
|
|
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
|
-
//
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|