create-wdio 9.32.0-alpha.6 → 10.0.0-alpha.148

package/AGENTS.md

@@ -0,0 +1,40 @@
+# create-wdio
+
+Scaffolds a WebdriverIO project (`npm create wdio` / `npm init wdio`) and the
+`wdio config` / `wdio install` commands re-exported to `@wdio/cli`.
+
+## Commands
+
+```sh
+pnpm run dev create-wdio
+pnpm run test:package create-wdio
+```
+
+## Tests
+
+Unit tests import `src/` directly. They do not prove a generated project runs;
+that is a smoke or example run.
+
+- `answers.generateTestFiles` is enforced in `createWDIOConfig` before it calls
+  `generateTestFiles`. The generator itself always renders the selected
+  framework templates. An empty directory listing does not prove generation
+  was skipped.
+- `getPackageVersion` reads this package's `package.json` and falls back to
+  `'unknown'`. Assert the version string. `expect.any(String)` also passes on
+  the fallback, which is what a `fs/promises` mock without `readFile` produces.
+- `createWDIOScript` shells out through `runProgram`. The call is owned by the
+  `runConfigCommand` test. Do not assert `child_process.spawn` for it.
+- Lit component templates ignore `installTestingLibrary`. A lit case named for
+  the absence of Testing Library must pass `installTestingLibrary: false`.
+- Declining the missing-config prompt exits the process. Mock `process.exit`
+  so that it throws; a non-throwing mock falls through into the wizard.
+
+## Wizard flags
+
+`src/answerFlags.ts` maps a command line flag to every `QUESTIONNAIRE`
+question. `npm init wdio` (commander) and `wdio config` (yargs) both read it,
+and `npm init wdio` forwards the flags to `wdio config`. When you add or
+rename a question or a choice, update its entry and the flag table in
+`website/docs/GettingStarted.md`. A flag for a question whose `when` is false,
+or a value outside its `choices`, is rejected after the answers are collected
+(`assertAnswerFlagsApply`).

package/README.md

@@ -64,6 +64,14 @@ You can pass the following command line flags to modify the bootstrap mechanism:
 * `--yes` - Will fill in all config defaults without prompting (default: `false`)
 * `--npm-tag` - use a specific NPM tag for `@wdio/cli` package (default: `latest`)
 
+Every question of the configuration wizard also has a flag, e.g. `--runner`, `--framework`, `--typescript`, `--browsers`, `--reporters` or `--services`. A flag answers its question and the wizard only asks the rest. Combined with `--yes` the setup runs without any prompt, e.g. for a coding agent or a CI job:
+
+```sh
+npm init wdio@latest ./e2e -- --yes --framework cucumber --no-typescript --reporters spec,junit
+```
+
+Run `npm init wdio@latest -- --help` for every flag and the values it accepts. Boolean flags take a `--no-` prefix. An invalid value, or a flag for a question that does not apply to your setup, exits with code 2.
+
 ----
 
 For more information on WebdriverIO see the [homepage](https://webdriver.io).

package/build/answerFlags.d.ts

@@ -0,0 +1,68 @@
+import type { Questionnair } from './types.js';
+type AnswerValue = string | null;
+export interface AnswerFlag {
+    /**
+     * camelCase option name, passed as `--kebab-case` on the command line
+     */
+    name: string;
+    answer: keyof Questionnair;
+    type: 'string' | 'boolean' | 'array';
+    desc: string;
+    /**
+     * CLI value → wizard answer value
+     */
+    choices?: () => Record<string, AnswerValue>;
+}
+/**
+ * Thrown for a flag value the wizard cannot use. The CLI prints the message
+ * and exits with code 2, like any other usage error.
+ */
+export declare class AnswerFlagError extends Error {
+    name: string;
+}
+/**
+ * Every wizard question that can be answered from the command line.
+ * `npm init wdio` and `wdio config` both read this list, so the flags and
+ * their help text stay the same in both commands.
+ */
+export declare const ANSWER_FLAGS: AnswerFlag[];
+/**
+ * Help text for one flag, with the accepted values if it has a fixed set.
+ */
+export declare function describeAnswerFlag(flag: AnswerFlag): string;
+/**
+ * Shared by the `--help` output of `npm init wdio` and `wdio config`.
+ */
+export declare const ANSWER_FLAGS_HELP: string;
+/**
+ * yargs options for `wdio config`, keyed in kebab-case so `--help` shows the
+ * flags as they are typed. yargs still sets the camelCase name on `argv`.
+ * No defaults: a flag that is not passed leaves the question to the wizard
+ * (or to `--yes`).
+ */
+export declare function getAnswerFlagYargsOptions(): Record<string, {
+    desc: string;
+    type: "boolean" | "string";
+    group: string;
+}>;
+/**
+ * Command line usage of a flag, e.g. `--runner <value>` or `--[no-]typescript`.
+ */
+export declare function answerFlagUsage(flag: AnswerFlag): string;
+/**
+ * Turn parsed command line options into wizard answers.
+ * Options that were not passed are left out, so the wizard still asks them.
+ */
+export declare function parseAnswerFlags(argv: Record<string, unknown>): Partial<Questionnair>;
+/**
+ * Turn the options `create-wdio` received back into flags for `wdio config`.
+ */
+export declare function answerFlagsToArgs(argv: Record<string, unknown>): string[];
+/**
+ * Check the answers given as flags against the finished questionnaire: every
+ * flag has to belong to a question the wizard asks for this setup, and its
+ * value has to be one the wizard offers there.
+ */
+export declare function assertAnswerFlagsApply(flagAnswers: Partial<Questionnair>, answers: Questionnair): void;
+export {};
+//# sourceMappingURL=answerFlags.d.ts.map

package/build/answerFlags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answerFlags.d.ts","sourceRoot":"","sources":["../src/answerFlags.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,KAAK,WAAW,GAAG,MAAM,GAAG,IAAI,CAAA;AAEhC,MAAM,WAAW,UAAU;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,YAAY,CAAA;IAC1B,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAA;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAC9C;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACtC,IAAI,SAAoB;CAC3B;AAkBD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,UAAU,EAoPnC,CAAA;AAcF;;GAEG;AACH,wBAAgB,kBAAkB,CAAE,IAAI,EAAE,UAAU,UAEnD;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAKlB,CAAA;AAEZ;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAK7B,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CACtF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAE,IAAI,EAAE,UAAU,UAKhD;AAoBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAmCtF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAe/D;AAwBD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAE,WAAW,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,YAAY,QA0BhG"}

package/build/cli/agent.d.ts

@@ -0,0 +1,17 @@
+export declare const AGENT_SECTION_HEADING = "## End-to-end tests (WebdriverIO v10)";
+/**
+ * The project-rules block from `website/docs/AIAgents.md`, plus a line that
+ * points at the installed skill. Kept here so `npm init wdio` can write it
+ * without the website package.
+ */
+export declare const AGENT_SECTION = "## End-to-end tests (WebdriverIO v10)\n\n- Docs: https://webdriver.io/llms.txt - fetch the relevant page as Markdown (append `.md`) before using an API you are not sure about. Do not use APIs from WebdriverIO v8 or older.\n- Config: `wdio.conf.ts`. Specs: `test/specs/**/*.e2e.ts`. Page objects: `test/pageobjects/`.\n- Run all tests: `npx wdio run wdio.conf.ts`\n- Run a single spec: `npx wdio run wdio.conf.ts --spec test/specs/login.e2e.ts`\n- Tests are async: always `await` commands, e.g. `await $('button').click()`. Never use the removed sync mode.\n- Prefer user-facing selectors: accessibility name or text (`$('aria/Submit')`, `$('button=Submit')`), then `data-testid`. Avoid XPath and generated CSS classes.\n- Rely on auto-waiting and `expect-webdriverio` matchers (`await expect($('h1')).toHaveText('Welcome')`) instead of `browser.pause()`.\n- To explore the app or verify a selector, use the `wdio-mcp` MCP server.\n- To drive the app from the shell, follow `.agents/skills/wdio-session/SKILL.md` (`npx wdio session`).\n- When a test fails, read the DevTools trace in `test-results/` (see `transcript.md`) before changing code.\n";
+/**
+ * The skill ships in this repo at `@wdio/session` and, for the published
+ * `create-wdio` package, as `templates/wdio-session/SKILL.md`.
+ */
+export declare function readSessionSkill(start?: string): string;
+/**
+ * Write the skill, the AGENTS.md section and `.wdio/session/` in `.gitignore`.
+ */
+export declare function writeAgentSupport(root: string): void;
+//# sourceMappingURL=agent.d.ts.map

package/build/cli/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/cli/agent.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,qBAAqB,0CAA0C,CAAA;AAE5E;;;;GAIG;AACH,eAAO,MAAM,aAAa,6nCAYzB,CAAA;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAE,KAAK,SAA+C,UAsBrF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAE,IAAI,EAAE,MAAM,QAsB9C"}

package/build/cli/config.d.ts

@@ -22,19 +22,19 @@ export declare const cmdArgs: {
         readonly default: "latest";
     };
 };
-export declare const builder: (yargs: Argv) => Argv<import("yargs").Omit<{}, "yarn" | "yes" | "npmTag"> & import("yargs").InferredOptionTypes<{
-    readonly yarn: {
+export declare const builder: (yargs: Argv) => Argv<import("yargs").Omit<{}, "yes" | "npmTag" | "yarn"> & import("yargs").InferredOptionTypes<{
+    yarn: {
         readonly type: "boolean";
         readonly desc: "Install packages via Yarn package manager.";
         readonly default: boolean;
     };
-    readonly yes: {
+    yes: {
         readonly alias: "y";
         readonly desc: "will fill in all config defaults without prompting";
         readonly type: "boolean";
         readonly default: false;
     };
-    readonly npmTag: {
+    npmTag: {
         readonly alias: "t";
         readonly desc: "define NPM tag to use for WebdriverIO related packages";
         readonly type: "string";

package/build/cli/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAIjC,OAAO,EAEH,gBAAgB,EACnB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAUzD,eAAO,MAAM,OAAO,WAAW,CAAA;AAC/B,eAAO,MAAM,IAAI,4EAA4E,CAAA;AAE7F,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;CAkBV,CAAA;AAEV,eAAO,MAAM,OAAO,GAAI,OAAO,IAAI;;;;;;;;;;;;;;;;;;GAKlC,CAAA;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,sBAAsB,EAAE,YAAY,0BAAmB;;;;GAQ1F;AAED,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAG,MAAM,YAAY,CAAA;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAIjC,OAAO,EAEH,gBAAgB,EACnB,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAUzD,eAAO,MAAM,OAAO,WAAW,CAAA;AAC/B,eAAO,MAAM,IAAI,4EAA4E,CAAA;AAE7F,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;CAkBV,CAAA;AAEV,eAAO,MAAM,OAAO,GAAI,OAAO,IAAI;;;;;;;;;;;;;;;;;;GAUlC,CAAA;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,sBAAsB,EAAE,YAAY,0BAAmB;;;;GAiB1F;AAED,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAG,MAAM,YAAY,CAAA;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA"}

package/build/cli/utils.d.ts

@@ -1,5 +1,5 @@
-import type { ParsedAnswers } from '../types.js';
-export declare function runConfigCommand(parsedAnswers: ParsedAnswers, npmTag: string): Promise<void>;
+import type { ParsedAnswers, Questionnair } from '../types.js';
+export declare function runConfigCommand(parsedAnswers: ParsedAnswers, npmTag: string, yes?: boolean): Promise<void>;
 /**
  * Helper utility used in `run` and `install` command to create config if none exist
  * @param {string} command to be executed by user
@@ -7,7 +7,19 @@ export declare function runConfigCommand(parsedAnswers: ParsedAnswers, npmTag: s
  * @param {Function} runConfigCmd runConfig method to be replaceable for unit testing
  */
 export declare function missingConfigurationPrompt(command: string, configPath: string, runConfigCmd?: Function): Promise<string>;
-export declare const parseAnswers: (yes: boolean) => Promise<ParsedAnswers>;
+/**
+ * Resolve where the generated WDIO TypeScript config should live.
+ * Never overwrite an existing root `tsconfig.json` — when that would happen
+ * (for example a direct-child spec glob like `e2e/*.ts`), fall back to a
+ * dedicated `tsconfig.e2e.json` / `tsconfig.wdio.json`.
+ */
+export declare function resolveTsConfigFilePath({ projectRootDir, hasRootTSConfig, specs, runnerShort }: {
+    projectRootDir: string;
+    hasRootTSConfig: boolean;
+    specs?: string;
+    runnerShort: string;
+}): string;
+export declare const parseAnswers: (yes: boolean, flagAnswers?: Partial<Questionnair>) => Promise<ParsedAnswers>;
 /**
  * Helper utility used in `run` and `install` command to check whether a config file currently exists
  * @param configPathNoExtension the file path to the WDIO config file without extension

package/build/cli/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/cli/utils.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAGhD,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,iBA+BlF;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAE,QAA2B,mBA+B9H;AAED,eAAO,MAAM,YAAY,GAAmB,KAAK,OAAO,KAAG,OAAO,CAAC,aAAa,CAyF/E,CAAA;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,qBAAqB,EAAC,MAAM,EAAE,UAAU,CAAC,EAAC,MAAM,GAAG,OAAO,CAAC,MAAM,GAAC,SAAS,CAAC,CAcrH"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/cli/utils.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAI9D,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAQ,iBAuC/F;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAE,QAA2B,mBAsB9H;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,EACpC,cAAc,EACd,eAAe,EACf,KAAK,EACL,WAAW,EACd,EAAE;IACC,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,OAAO,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;CACtB,UAwBA;AAED,eAAO,MAAM,YAAY,GAAmB,KAAK,OAAO,EAAE,cAAa,OAAO,CAAC,YAAY,CAAM,KAAG,OAAO,CAAC,aAAa,CA2ExH,CAAA;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,qBAAqB,EAAC,MAAM,EAAE,UAAU,CAAC,EAAC,MAAM,GAAG,OAAO,CAAC,MAAM,GAAC,SAAS,CAAC,CAcrH"}