qualiow-exploratory-testing 1.0.0 → 1.2.0

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 (41) hide show
  1. package/README.md +85 -0
  2. package/bin/mcli +16 -0
  3. package/bin/mobile-cli.mjs +573 -0
  4. package/bin/wadb +6 -0
  5. package/bin/wk-ios +58 -0
  6. package/bin/wkeval.mjs +44 -0
  7. package/data/knowledge/learned-patterns.md +85 -0
  8. package/data/knowledge/manifest.yml +2 -1
  9. package/data/targets/_example-mobile-emulation.yml +52 -0
  10. package/data/targets/_example-native-mobile.yml +61 -0
  11. package/data/targets/_example-sim-android-chrome.yml +81 -0
  12. package/data/targets/_example-sim-ios-safari.yml +80 -0
  13. package/dist/cli/index.js +156 -33
  14. package/dist/cli/index.js.map +1 -1
  15. package/dist/index.d.ts +260 -527
  16. package/dist/index.js +142 -12
  17. package/dist/index.js.map +1 -1
  18. package/docs/MOBILE-SETUP.md +92 -0
  19. package/package.json +33 -11
  20. package/scripts/doctor-mobile.sh +143 -0
  21. package/scripts/setup-mobile.sh +213 -0
  22. package/skills/qa-explore/SKILL.md +2 -1
  23. package/skills/qa-explore/phases/00-setup.md +22 -1
  24. package/skills/qa-explore/phases/01-auth.md +4 -0
  25. package/skills/qa-explore/phases/03-discovery.md +14 -0
  26. package/skills/qa-explore/phases/05-features.md +20 -0
  27. package/skills/qa-explore/phases/06-edge-cases.md +2 -0
  28. package/skills/qa-explore/phases/07-reporting.md +11 -0
  29. package/skills/qa-explore/references/playwright-agents-integration.md +126 -0
  30. package/skills/qa-explore-mobile/SKILL.md +146 -0
  31. package/skills/qa-explore-mobile/phases/00-setup.md +203 -0
  32. package/skills/qa-explore-mobile/phases/01-auth.md +127 -0
  33. package/skills/qa-explore-mobile/phases/02-charter.md +70 -0
  34. package/skills/qa-explore-mobile/phases/03-discovery.md +79 -0
  35. package/skills/qa-explore-mobile/phases/04-journeys.md +49 -0
  36. package/skills/qa-explore-mobile/phases/05-features.md +72 -0
  37. package/skills/qa-explore-mobile/phases/06-edge-cases.md +157 -0
  38. package/skills/qa-explore-mobile/phases/07-reporting.md +123 -0
  39. package/skills/qa-explore-mobile/references/mobile-edges.md +117 -0
  40. package/skills/qa-explore-quick/SKILL.md +7 -0
  41. package/skills/qa-target-setup/SKILL.md +12 -0
package/dist/cli/index.js CHANGED
@@ -228,21 +228,41 @@ import { ZodError } from "zod";
228
228
  // src/schemas/target.schema.ts
229
229
  import { z } from "zod";
230
230
  var AuthConfigSchema = z.object({
231
- strategy: z.enum(["none", "storage_state", "credentials", "token"]),
231
+ // 'in-app' (native mobile: login/signup inside the app) and 'interactive-sso'
232
+ // (mobile web: one-time human SSO/MFA login the browser profile persists) are
233
+ // mobile-only strategies used by /qa-explore-mobile.
234
+ strategy: z.enum([
235
+ "none",
236
+ "storage_state",
237
+ "credentials",
238
+ "token",
239
+ "in-app",
240
+ "interactive-sso"
241
+ ]),
232
242
  state_file: z.string().optional(),
233
243
  login_url: z.string().url().optional(),
234
244
  credentials: z.object({
235
245
  username: z.string(),
236
246
  password: z.string()
237
247
  }).optional(),
238
- token: z.string().optional()
248
+ token: z.string().optional(),
249
+ identity_provider: z.string().optional(),
250
+ // Staging builds sometimes accept a fixed OTP — recorded so the auth phase can
251
+ // use it instead of waiting for a real code. Never a real credential.
252
+ static_otp: z.string().optional(),
253
+ test_email_pattern: z.string().optional()
239
254
  });
240
255
  var BrowserConfigSchema = z.object({
241
256
  headless: z.boolean(),
242
257
  viewport: z.object({
243
258
  width: z.number().int().positive(),
244
259
  height: z.number().int().positive()
245
- })
260
+ }),
261
+ // Optional engine selection + Playwright device descriptor for mobile-web
262
+ // emulation targets (e.g. engine: webkit, device: "iPhone 15").
263
+ engine: z.enum(["chromium", "webkit", "firefox"]).optional(),
264
+ channel: z.string().optional(),
265
+ device: z.string().optional()
246
266
  });
247
267
  var ScopeConfigSchema = z.object({
248
268
  start_pages: z.array(z.string()).optional(),
@@ -256,10 +276,12 @@ var SafetyConfigSchema = z.object({
256
276
  no_file_upload: z.boolean().optional(),
257
277
  no_delete_actions: z.boolean().optional()
258
278
  });
259
- var TargetConfigSchema = z.object({
279
+ var WebTargetConfigSchema = z.object({
260
280
  id: z.string().min(1),
261
281
  name: z.string().min(1),
262
- base_url: z.string().url(),
282
+ // '' is allowed for the ad-hoc template (_default.yml) where the URL is
283
+ // provided at session start rather than in the config.
284
+ base_url: z.union([z.literal(""), z.string().url()]),
263
285
  domain: z.string().min(1),
264
286
  auth: AuthConfigSchema,
265
287
  browser: BrowserConfigSchema,
@@ -267,6 +289,65 @@ var TargetConfigSchema = z.object({
267
289
  safety: SafetyConfigSchema.optional(),
268
290
  notes: z.string().optional()
269
291
  });
292
+ var MobileDeviceConfigSchema = z.object({
293
+ name: z.string().optional(),
294
+ // iOS simulator name (portable across machines)
295
+ udid: z.string().optional(),
296
+ // iOS simulator UDID (takes precedence over name)
297
+ avd: z.string().optional(),
298
+ // Android AVD name
299
+ serial: z.string().optional()
300
+ // Android serial once booted (e.g. emulator-5554)
301
+ });
302
+ var MobileAppConfigSchema = z.object({
303
+ bundle_id: z.string().optional(),
304
+ // iOS bundle id (or browser bundle in web mode)
305
+ package: z.string().optional(),
306
+ // Android application id (or browser package)
307
+ app_paths: z.array(z.string()).optional(),
308
+ // iOS .app artifact(s) — native mode
309
+ apk_paths: z.array(z.string()).optional()
310
+ // Android APK(s) — native mode
311
+ });
312
+ var MobileWebConfigSchema = z.object({
313
+ base_url: z.string().url(),
314
+ start_url: z.string().url().optional()
315
+ });
316
+ var SourceRepoConfigSchema = z.object({
317
+ path: z.string(),
318
+ build_commands: z.record(z.string(), z.string()).optional()
319
+ });
320
+ var MobileScopeConfigSchema = z.object({
321
+ start_screen: z.string().optional(),
322
+ start_url: z.string().optional(),
323
+ include_patterns: z.array(z.string()).optional(),
324
+ exclude_patterns: z.array(z.string()).optional()
325
+ });
326
+ var MobileTargetConfigSchema = z.object({
327
+ id: z.string().min(1),
328
+ name: z.string().min(1),
329
+ platform: z.enum(["ios", "android"]),
330
+ // discriminates mobile from web targets
331
+ domain: z.string().min(1),
332
+ device: MobileDeviceConfigSchema,
333
+ app: MobileAppConfigSchema,
334
+ web: MobileWebConfigSchema.optional(),
335
+ // present → WEB mode; absent → NATIVE mode
336
+ auth: AuthConfigSchema,
337
+ scope: MobileScopeConfigSchema.optional(),
338
+ safety: SafetyConfigSchema.optional(),
339
+ source_repo: SourceRepoConfigSchema.optional(),
340
+ notes: z.string().optional()
341
+ });
342
+ var TargetConfigSchema = z.custom().superRefine((data, ctx) => {
343
+ const isMobile = typeof data === "object" && data !== null && "platform" in data;
344
+ const branch = isMobile ? MobileTargetConfigSchema : WebTargetConfigSchema;
345
+ const result = branch.safeParse(data);
346
+ if (!result.success) {
347
+ for (const issue of result.error.issues)
348
+ ctx.addIssue(issue);
349
+ }
350
+ });
270
351
 
271
352
  // src/schemas/knowledge-entry.schema.ts
272
353
  import { z as z2 } from "zod";
@@ -616,11 +697,13 @@ function pad(str, len) {
616
697
 
617
698
  // src/cli/commands/report.ts
618
699
  import { Command as Command4 } from "commander";
619
- import { resolve as resolve5, join as join5, basename as basename2 } from "path";
620
- import { existsSync as existsSync5, readdirSync as readdirSync4, writeFileSync as writeFileSync2 } from "fs";
700
+ import { resolve as resolve6, join as join5, basename as basename2 } from "path";
701
+ import { existsSync as existsSync6, readdirSync as readdirSync4, writeFileSync as writeFileSync2 } from "fs";
621
702
  import chalk4 from "chalk";
622
703
 
623
704
  // src/formatters/html-report.ts
705
+ import { readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
706
+ import { resolve as resolve5, extname } from "path";
624
707
  import Handlebars from "handlebars";
625
708
 
626
709
  // src/utils/parse-session.ts
@@ -871,6 +954,17 @@ var HTML_TEMPLATE = `<!DOCTYPE html>
871
954
  a { color: #3498db; text-decoration: none; }
872
955
  a:hover { text-decoration: underline; }
873
956
 
957
+ .screenshot-container { margin: 0.75rem 0; }
958
+ .screenshot-img {
959
+ max-width: 100%;
960
+ border-radius: 6px;
961
+ border: 1px solid #1e2a3a;
962
+ cursor: pointer;
963
+ transition: transform 0.2s;
964
+ }
965
+ .screenshot-img:hover { transform: scale(1.02); }
966
+ .screenshot-label { font-size: 0.8rem; color: #8899aa; margin-top: 0.25rem; }
967
+
874
968
  .container { max-width: 960px; margin: 0 auto; }
875
969
 
876
970
  /* Header */
@@ -1158,8 +1252,11 @@ var HTML_TEMPLATE = `<!DOCTYPE html>
1158
1252
 
1159
1253
  {{#if this.hasEvidence}}
1160
1254
  <div class="bug-section-label">Evidence</div>
1161
- {{#each this.evidence.screenshots}}
1162
- <p class="evidence-item">Screenshot: {{this}}</p>
1255
+ {{#each this.embeddedScreenshots}}
1256
+ <div class="screenshot-container">
1257
+ <img src="{{this.dataUri}}" alt="{{this.filename}}" class="screenshot-img" />
1258
+ <p class="screenshot-label">{{this.filename}}</p>
1259
+ </div>
1163
1260
  {{/each}}
1164
1261
  {{#each this.evidence.console_errors}}
1165
1262
  <p class="evidence-item">Console: {{this}}</p>
@@ -1233,11 +1330,37 @@ async function generateHtmlReport(sessionDir) {
1233
1330
  for (const bug of session.bugs) {
1234
1331
  counts[bug.severity]++;
1235
1332
  }
1236
- const bugsForTemplate = session.bugs.map((bug) => ({
1237
- ...bug,
1238
- business_impact_summary: summarizeBusinessImpact(bug.business_impact),
1239
- hasEvidence: bug.evidence.screenshots.length > 0 || bug.evidence.console_errors.length > 0
1240
- }));
1333
+ const bugsForTemplate = session.bugs.map((bug) => {
1334
+ const embeddedScreenshots = bug.evidence.screenshots.map((screenshotRef) => {
1335
+ const cleaned = screenshotRef.replace(/`/g, "").replace(/\s*\(.*?\)\s*$/, "").trim();
1336
+ const possiblePaths = [
1337
+ resolve5(sessionDir, cleaned),
1338
+ resolve5(sessionDir, "screenshots", cleaned),
1339
+ resolve5(sessionDir, cleaned.replace(/^screenshots\//, "")),
1340
+ resolve5(sessionDir, "screenshots", cleaned.replace(/^screenshots\//, ""))
1341
+ ];
1342
+ for (const imgPath of possiblePaths) {
1343
+ if (existsSync5(imgPath)) {
1344
+ try {
1345
+ const ext = extname(imgPath).toLowerCase().replace(".", "");
1346
+ const mime = ext === "jpg" ? "image/jpeg" : `image/${ext || "png"}`;
1347
+ const data = readFileSync5(imgPath).toString("base64");
1348
+ const filename = imgPath.split("/").pop() || screenshotRef;
1349
+ return { dataUri: `data:${mime};base64,${data}`, filename };
1350
+ } catch {
1351
+ return null;
1352
+ }
1353
+ }
1354
+ }
1355
+ return null;
1356
+ }).filter(Boolean);
1357
+ return {
1358
+ ...bug,
1359
+ business_impact_summary: summarizeBusinessImpact(bug.business_impact),
1360
+ hasEvidence: embeddedScreenshots.length > 0 || bug.evidence.console_errors.length > 0,
1361
+ embeddedScreenshots
1362
+ };
1363
+ });
1241
1364
  const html = compiledTemplate({
1242
1365
  meta,
1243
1366
  totalBugs: session.bugs.length,
@@ -1450,8 +1573,8 @@ function reportCommand() {
1450
1573
  }
1451
1574
  async function runReport(options) {
1452
1575
  const cwd = process.cwd();
1453
- const sessionsDir = resolve5(cwd, "output", "sessions");
1454
- if (!existsSync5(sessionsDir)) {
1576
+ const sessionsDir = resolve6(cwd, "output", "sessions");
1577
+ if (!existsSync6(sessionsDir)) {
1455
1578
  console.error(chalk4.red("No sessions directory found. Run `npx qualiow init` first."));
1456
1579
  process.exit(1);
1457
1580
  }
@@ -1467,7 +1590,7 @@ Session: ${sessionName}`));
1467
1590
  switch (format) {
1468
1591
  case "md": {
1469
1592
  const reportPath = join5(sessionDir, "session-report.md");
1470
- if (existsSync5(reportPath)) {
1593
+ if (existsSync6(reportPath)) {
1471
1594
  console.log(chalk4.green(`
1472
1595
  Report: ${reportPath}`));
1473
1596
  } else {
@@ -1512,7 +1635,7 @@ function resolveSessionDir(sessionsDir, sessionId) {
1512
1635
  return join5(sessionsDir, dirs2[dirs2.length - 1]);
1513
1636
  }
1514
1637
  const exactPath = join5(sessionsDir, sessionId);
1515
- if (existsSync5(exactPath)) {
1638
+ if (existsSync6(exactPath)) {
1516
1639
  return exactPath;
1517
1640
  }
1518
1641
  const dirs = readdirSync4(sessionsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && d.name.includes(sessionId)).map((d) => d.name).sort();
@@ -1524,8 +1647,8 @@ function resolveSessionDir(sessionsDir, sessionId) {
1524
1647
 
1525
1648
  // src/cli/commands/explore.ts
1526
1649
  import { Command as Command5 } from "commander";
1527
- import { resolve as resolve6, join as join6 } from "path";
1528
- import { existsSync as existsSync6, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
1650
+ import { resolve as resolve7, join as join6 } from "path";
1651
+ import { existsSync as existsSync7, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
1529
1652
  import { execSync } from "child_process";
1530
1653
  import chalk5 from "chalk";
1531
1654
  function exploreCommand() {
@@ -1551,8 +1674,8 @@ async function runExplore(url, options) {
1551
1674
  }
1552
1675
  let targetName = "adhoc";
1553
1676
  if (options.target) {
1554
- const targetPath = resolve6(cwd, "data", "targets", `${options.target}.yml`);
1555
- if (!existsSync6(targetPath)) {
1677
+ const targetPath = resolve7(cwd, "data", "targets", `${options.target}.yml`);
1678
+ if (!existsSync7(targetPath)) {
1556
1679
  console.error(
1557
1680
  chalk5.red(`Target config not found: ${targetPath}`)
1558
1681
  );
@@ -1571,8 +1694,8 @@ async function runExplore(url, options) {
1571
1694
  console.log(chalk5.green(` \u2713 Target config "${options.target}" is valid`));
1572
1695
  }
1573
1696
  if (options.context) {
1574
- const contextPath = resolve6(cwd, options.context);
1575
- if (!existsSync6(contextPath)) {
1697
+ const contextPath = resolve7(cwd, options.context);
1698
+ if (!existsSync7(contextPath)) {
1576
1699
  console.error(chalk5.red(`Context file not found: ${contextPath}`));
1577
1700
  process.exit(1);
1578
1701
  }
@@ -1588,7 +1711,7 @@ async function runExplore(url, options) {
1588
1711
  String(now.getMinutes()).padStart(2, "0")
1589
1712
  ].join("");
1590
1713
  const sessionName = `${timestamp}-${targetName}`;
1591
- const sessionDir = resolve6(cwd, "output", "sessions", sessionName);
1714
+ const sessionDir = resolve7(cwd, "output", "sessions", sessionName);
1592
1715
  if (options.dryRun) {
1593
1716
  console.log("");
1594
1717
  console.log(chalk5.cyan.bold("Dry run \u2014 no files created"));
@@ -1666,8 +1789,8 @@ async function runExplore(url, options) {
1666
1789
 
1667
1790
  // src/cli/commands/gather.ts
1668
1791
  import { Command as Command6 } from "commander";
1669
- import { resolve as resolve7 } from "path";
1670
- import { existsSync as existsSync7, mkdirSync as mkdirSync3 } from "fs";
1792
+ import { resolve as resolve8 } from "path";
1793
+ import { existsSync as existsSync8, mkdirSync as mkdirSync3 } from "fs";
1671
1794
  import { execSync as execSync2 } from "child_process";
1672
1795
  import chalk6 from "chalk";
1673
1796
  function gatherCommand() {
@@ -1684,7 +1807,7 @@ function gatherCommand() {
1684
1807
  async function runGather(source, options) {
1685
1808
  const cwd = process.cwd();
1686
1809
  const isUrl = isValidUrl(source);
1687
- const isFile = !isUrl && existsSync7(resolve7(cwd, source));
1810
+ const isFile = !isUrl && existsSync8(resolve8(cwd, source));
1688
1811
  if (!isUrl && !isFile) {
1689
1812
  console.error(chalk6.red(`Source not found: "${source}"`));
1690
1813
  console.error(chalk6.white(" Provide a valid file path or URL."));
@@ -1693,21 +1816,21 @@ async function runGather(source, options) {
1693
1816
  if (isUrl) {
1694
1817
  console.log(chalk6.green(` \u2713 Source is a URL: ${source}`));
1695
1818
  } else {
1696
- console.log(chalk6.green(` \u2713 Source file found: ${resolve7(cwd, source)}`));
1819
+ console.log(chalk6.green(` \u2713 Source file found: ${resolve8(cwd, source)}`));
1697
1820
  }
1698
1821
  if (options.domain) {
1699
- const domainPath = resolve7(cwd, "data", "domains", `${options.domain}.yml`);
1700
- if (!existsSync7(domainPath)) {
1822
+ const domainPath = resolve8(cwd, "data", "domains", `${options.domain}.yml`);
1823
+ if (!existsSync8(domainPath)) {
1701
1824
  console.error(chalk6.red(`Domain config not found: ${domainPath}`));
1702
1825
  console.error(chalk6.white(" Available domains: npx qualiow list domains"));
1703
1826
  process.exit(1);
1704
1827
  }
1705
1828
  console.log(chalk6.green(` \u2713 Domain config "${options.domain}" found`));
1706
1829
  }
1707
- const outputDir = resolve7(cwd, "output", "context");
1830
+ const outputDir = resolve8(cwd, "output", "context");
1708
1831
  mkdirSync3(outputDir, { recursive: true });
1709
1832
  if (options.output) {
1710
- console.log(chalk6.green(` \u2713 Output will be saved to: ${resolve7(cwd, options.output)}`));
1833
+ console.log(chalk6.green(` \u2713 Output will be saved to: ${resolve8(cwd, options.output)}`));
1711
1834
  } else {
1712
1835
  console.log(chalk6.green(` \u2713 Output directory ready: ${outputDir}`));
1713
1836
  }