quiesco 0.6.0 → 0.8.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 (64) hide show
  1. package/README.md +2 -2
  2. package/dist/app-dir.d.ts +13 -0
  3. package/dist/app-dir.d.ts.map +1 -0
  4. package/dist/app-dir.js +22 -0
  5. package/dist/app-dir.js.map +1 -0
  6. package/dist/cli.d.ts +1 -1
  7. package/dist/cli.d.ts.map +1 -1
  8. package/dist/cli.js +6 -5
  9. package/dist/cli.js.map +1 -1
  10. package/dist/commands/build.d.ts +1 -1
  11. package/dist/commands/build.d.ts.map +1 -1
  12. package/dist/commands/build.js +21 -11
  13. package/dist/commands/build.js.map +1 -1
  14. package/dist/commands/doctor.d.ts +1 -1
  15. package/dist/commands/doctor.d.ts.map +1 -1
  16. package/dist/commands/doctor.js +75 -37
  17. package/dist/commands/doctor.js.map +1 -1
  18. package/dist/commands/init.d.ts.map +1 -1
  19. package/dist/commands/init.js +91 -16
  20. package/dist/commands/init.js.map +1 -1
  21. package/dist/commands/list.d.ts +1 -1
  22. package/dist/commands/list.d.ts.map +1 -1
  23. package/dist/commands/list.js +4 -2
  24. package/dist/commands/list.js.map +1 -1
  25. package/dist/commands/test.d.ts +2 -2
  26. package/dist/commands/test.d.ts.map +1 -1
  27. package/dist/commands/test.js +4 -2
  28. package/dist/commands/test.js.map +1 -1
  29. package/dist/commands/ui.d.ts +1 -1
  30. package/dist/commands/ui.d.ts.map +1 -1
  31. package/dist/commands/ui.js +4 -2
  32. package/dist/commands/ui.js.map +1 -1
  33. package/dist/commands/upgrade.d.ts.map +1 -1
  34. package/dist/commands/upgrade.js +58 -28
  35. package/dist/commands/upgrade.js.map +1 -1
  36. package/dist/context.d.ts +8 -0
  37. package/dist/context.d.ts.map +1 -1
  38. package/dist/context.js +22 -0
  39. package/dist/context.js.map +1 -1
  40. package/dist/dev-server.d.ts.map +1 -1
  41. package/dist/dev-server.js +4 -2
  42. package/dist/dev-server.js.map +1 -1
  43. package/dist/runner.d.ts +15 -0
  44. package/dist/runner.d.ts.map +1 -0
  45. package/dist/runner.js +41 -0
  46. package/dist/runner.js.map +1 -0
  47. package/dist/setup-steps.d.ts +8 -3
  48. package/dist/setup-steps.d.ts.map +1 -1
  49. package/dist/setup-steps.js +18 -8
  50. package/dist/setup-steps.js.map +1 -1
  51. package/package.json +2 -2
  52. package/src/app-dir.ts +26 -0
  53. package/src/cli.ts +6 -5
  54. package/src/commands/build.ts +20 -11
  55. package/src/commands/doctor.ts +76 -38
  56. package/src/commands/init.ts +101 -15
  57. package/src/commands/list.ts +4 -2
  58. package/src/commands/test.ts +5 -3
  59. package/src/commands/ui.ts +4 -2
  60. package/src/commands/upgrade.ts +58 -27
  61. package/src/context.ts +23 -0
  62. package/src/dev-server.ts +4 -2
  63. package/src/runner.ts +47 -0
  64. package/src/setup-steps.ts +20 -8
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "quiesco",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
4
4
  "description": "Quiesco command line: init, test (with a progress bar), ui, list, doctor, tree",
5
5
  "license": "MIT",
6
6
  "author": "h2nology",
@@ -44,7 +44,7 @@
44
44
  "src"
45
45
  ],
46
46
  "dependencies": {
47
- "@quiesco/core": "0.6.0"
47
+ "@quiesco/core": "0.8.0"
48
48
  },
49
49
  "scripts": {
50
50
  "build": "tsc -b",
package/src/app-dir.ts ADDED
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Where the Expo app is (issue #54): the test project's directory, or `appDir` in quiesco.config (tests in
3
+ * a package of their own: a monorepo, or `app/` and `e2e/` side by side). `--app-dir` overrides it.
4
+ */
5
+ import path from 'node:path';
6
+
7
+ import type { CliContext } from './context.js';
8
+
9
+ /** The option the commands that work on the app take. */
10
+ export const APP_DIR_OPTION = '--app-dir';
11
+
12
+ /**
13
+ * The context for the app: `ctx` itself when the app is the project directory, else a copy whose `cwd`
14
+ * is the app's directory. `flag` (relative to the working directory) wins over `config.appDir`.
15
+ */
16
+ export function appContext(ctx: CliContext, config: { appDir?: string } | null, flag?: string): CliContext {
17
+ const dir = flag !== undefined ? path.resolve(ctx.cwd, flag) : config?.appDir !== undefined ? path.resolve(ctx.cwd, config.appDir) : ctx.cwd;
18
+ return path.resolve(dir) === path.resolve(ctx.cwd) ? ctx : { ...ctx, cwd: dir };
19
+ }
20
+
21
+ /** How a path in the app is shown: relative to the working directory when near it, else absolute. */
22
+ export function inApp(ctx: CliContext, app: CliContext, file = ''): string {
23
+ const abs = path.join(app.cwd, file);
24
+ const rel = path.relative(ctx.cwd, abs);
25
+ return rel === '' ? '.' : rel.split(path.sep).filter((p) => p === '..').length > 2 ? abs : rel;
26
+ }
package/src/cli.ts CHANGED
@@ -15,19 +15,20 @@ export const HELP = `Usage: quiesco <command> [options]
15
15
 
16
16
  Commands:
17
17
  init Set Quiesco up in this Expo project (dependencies, config plugin, Metro, entry, config, features)
18
- --platforms ios,android,web --packages <dir> (install from tarballs) --skip-install
18
+ --platforms ios,android,web --runner vitest|jest|cucumber (asked when not given; default vitest)
19
+ --packages <dir> (install from tarballs) --skip-install
19
20
  --upgrade: bring a project set up by an older version to this one (packages, config, files)
20
- --dry-run (list the changes only)
21
+ --dry-run (list the changes only) --app-dir <dir> (the app, when the tests are elsewhere)
21
22
  build Build the app for e2e tests (prebuild + xcodebuild / gradle) into apps.<platform>.binaryPath
22
- ios|android --force (also when the native inputs did not change)
23
- test Run the tests with cucumber-js (or --runner jest|vitest); other arguments go to the runner unchanged
23
+ ios|android --force (also when the native inputs did not change) --app-dir <dir>
24
+ test Run the tests with the project's runner (or --runner vitest|jest|cucumber); other arguments go to the runner unchanged
24
25
  --platform ios|android|web --workers N (N devices in parallel) (quiesco test --help for more)
25
26
  ui Open the test UI: run tests from the browser and watch them live (needs @quiesco/ui)
26
27
  --platform ios|android|web --runner … --port N --no-open
27
28
  list List the tests the runner would run, without running them
28
29
  --runner cucumber|jest|vitest --json
29
30
  doctor Check the tools and the project setup
30
- --platform ios|android|web
31
+ --platform ios|android|web --app-dir <dir> (the app, when the tests are elsewhere; or appDir in quiesco.config)
31
32
  tree Print the element tree of the running app (to find testIDs)
32
33
  --launch (boot the device and launch the app first) --json --timeout <ms> --platform …
33
34
  devices List the simulators / AVDs Quiesco created for parallel workers
@@ -8,6 +8,8 @@
8
8
  * A Debug build is skipped when its native inputs (app config, dependencies and their installed versions)
9
9
  * did not change since the last build and the binary is still there; `--force` builds anyway. Release builds
10
10
  * embed the JS bundle, so they are always built.
11
+ * With `appDir` (or `--app-dir`, issue #54) the app is built in that directory; `binaryPath` stays relative
12
+ * to the working directory (the config's).
11
13
  */
12
14
  import { createHash } from 'node:crypto';
13
15
  import fs from 'node:fs';
@@ -16,14 +18,16 @@ import path from 'node:path';
16
18
  import type { QuiescoConfig } from '@quiesco/core';
17
19
  import { loadConfig } from '@quiesco/core';
18
20
 
21
+ import { APP_DIR_OPTION, appContext } from '../app-dir.js';
19
22
  import type { CliContext } from '../context.js';
20
23
  import { takeOption } from '../context.js';
21
24
 
22
- export const BUILD_HELP = `Usage: quiesco build ios|android [--force]
25
+ export const BUILD_HELP = `Usage: quiesco build ios|android [--force] [--app-dir <dir>]
23
26
 
24
27
  Builds the app for e2e tests (EXPO_PUBLIC_QUIESCO=1: expo prebuild, then xcodebuild / gradle) and writes it
25
28
  to apps.<platform>.binaryPath in quiesco.config. A Debug build is skipped when the native inputs (app config,
26
- dependencies) did not change since the last one; --force builds anyway.`;
29
+ dependencies) did not change since the last one; --force builds anyway. The app is the one in appDir
30
+ (quiesco.config) or --app-dir when the tests are in a package of their own.`;
27
31
 
28
32
  export interface BuildDeps {
29
33
  loadConfig: (cwd: string) => Promise<QuiescoConfig>;
@@ -74,7 +78,8 @@ export async function buildCommand(args: readonly string[], ctx: CliContext, dep
74
78
  return 0;
75
79
  }
76
80
  const force = args.includes('--force');
77
- const rest = takeOption(args.filter((a) => a !== '--force'), '--platform');
81
+ const appDirOpt = takeOption(args.filter((a) => a !== '--force'), APP_DIR_OPTION);
82
+ const rest = takeOption(appDirOpt.rest, '--platform');
78
83
  const platform = rest.value ?? rest.rest[0];
79
84
  if (platform !== 'ios' && platform !== 'android') {
80
85
  ctx.err(`quiesco build: choose ios or android (quiesco build ios). The web needs no build: quiesco test starts Metro, or export it with EXPO_PUBLIC_QUIESCO=1 npx expo export --platform web.`);
@@ -87,6 +92,7 @@ export async function buildCommand(args: readonly string[], ctx: CliContext, dep
87
92
  ctx.err(`quiesco build: ${(e as Error).message}`);
88
93
  return 1;
89
94
  }
95
+ const app = appContext(ctx, config, appDirOpt.value);
90
96
  const binaryPath = config.apps[platform]?.binaryPath;
91
97
  if (binaryPath === undefined) {
92
98
  ctx.err(`quiesco build: apps.${platform}.binaryPath is not set in quiesco.config: that is where the build goes (npx quiesco init writes it).`);
@@ -99,8 +105,8 @@ export async function buildCommand(args: readonly string[], ctx: CliContext, dep
99
105
  }
100
106
  const release = platform === 'ios' ? !/^debug$/i.test(ios?.configuration ?? '') : androidVariant(binaryPath) === 'release';
101
107
  const binary = path.resolve(ctx.cwd, binaryPath);
102
- const stampFile = path.join(ctx.cwd, '.expo', 'quiesco', `build-${platform}.json`);
103
- const fingerprint = nativeFingerprint(ctx, platform, binaryPath);
108
+ const stampFile = path.join(app.cwd, '.expo', 'quiesco', `build-${platform}.json`);
109
+ const fingerprint = nativeFingerprint(app, platform, binaryPath);
104
110
  if (!force && !release && ctx.exists(binary)) {
105
111
  const stamp = ctx.readFile(stampFile);
106
112
  if (stamp !== null && (JSON.parse(stamp) as { fingerprint?: string }).fingerprint === fingerprint) {
@@ -111,27 +117,30 @@ export async function buildCommand(args: readonly string[], ctx: CliContext, dep
111
117
 
112
118
  const env = { ...ctx.env, EXPO_PUBLIC_QUIESCO: '1' };
113
119
  ctx.out(`quiesco build: expo prebuild --platform ${platform} (EXPO_PUBLIC_QUIESCO=1)`);
114
- let code = await ctx.run('npx', ['expo', 'prebuild', '--platform', platform], { cwd: ctx.cwd, env });
120
+ if (app !== ctx) ctx.out(`quiesco build: the app in ${app.cwd}`);
121
+ let code = await ctx.run('npx', ['expo', 'prebuild', '--platform', platform], { cwd: app.cwd, env });
115
122
  if (code !== 0) return fail(ctx, 'expo prebuild', code);
116
123
 
117
124
  if (ios !== null) {
118
125
  const workspace = path.join('ios', `${ios.name}.xcworkspace`);
119
- if (!ctx.exists(path.join(ctx.cwd, workspace))) {
126
+ if (!app.exists(path.join(app.cwd, workspace))) {
120
127
  ctx.err(`quiesco build: ${workspace} not found after prebuild. The .app name in apps.ios.binaryPath must be the Xcode scheme (expo prebuild names it after expo.name).`);
121
128
  return 1;
122
129
  }
123
- const xcode = ['-workspace', workspace, '-scheme', ios.name, '-configuration', ios.configuration, '-sdk', 'iphonesimulator', '-destination', 'generic/platform=iOS Simulator', '-derivedDataPath', ios.derivedData, '-quiet', 'build'];
130
+ // binaryPath (and so the derived data) is relative to the working directory; xcodebuild runs in the app.
131
+ const derivedData = path.relative(app.cwd, path.resolve(ctx.cwd, ios.derivedData)) || '.';
132
+ const xcode = ['-workspace', workspace, '-scheme', ios.name, '-configuration', ios.configuration, '-sdk', 'iphonesimulator', '-destination', 'generic/platform=iOS Simulator', '-derivedDataPath', derivedData, '-quiet', 'build'];
124
133
  ctx.out(`quiesco build: xcodebuild ${xcode.join(' ')}`);
125
- code = await ctx.run('xcodebuild', xcode, { cwd: ctx.cwd, env });
134
+ code = await ctx.run('xcodebuild', xcode, { cwd: app.cwd, env });
126
135
  if (code !== 0) return fail(ctx, 'xcodebuild', code);
127
136
  } else {
128
137
  const variant = androidVariant(binaryPath);
129
138
  const task = `assemble${variant === 'release' ? 'Release' : 'Debug'}`;
130
139
  const gradlew = ctx.platform === 'win32' ? 'gradlew.bat' : './gradlew';
131
140
  ctx.out(`quiesco build: ${gradlew} ${task} (in android/)`);
132
- code = await ctx.run(gradlew, [task], { cwd: path.join(ctx.cwd, 'android'), env });
141
+ code = await ctx.run(gradlew, [task], { cwd: path.join(app.cwd, 'android'), env });
133
142
  if (code !== 0) return fail(ctx, `gradle ${task}`, code);
134
- const output = path.join(ctx.cwd, 'android', 'app', 'build', 'outputs', 'apk', variant, `app-${variant}.apk`);
143
+ const output = path.join(app.cwd, 'android', 'app', 'build', 'outputs', 'apk', variant, `app-${variant}.apk`);
135
144
  if (path.resolve(output) !== binary) {
136
145
  fs.mkdirSync(path.dirname(binary), { recursive: true });
137
146
  fs.copyFileSync(output, binary);
@@ -1,7 +1,8 @@
1
1
  /**
2
- * `quiesco doctor [--platform ios|android|web]` (requirements.md §6.12): check the environment and the
3
- * project's Quiesco setup. Every check says what is wrong and how to fix it; exit code 1 when a check
4
- * fails (warnings do not fail).
2
+ * `quiesco doctor [--platform ios|android|web] [--app-dir <dir>]` (requirements.md §6.12): check the
3
+ * environment and the project's Quiesco setup. Every check says what is wrong and how to fix it; exit code
4
+ * 1 when a check fails (warnings do not fail). With `appDir` (issue #54) the app's checks run in the app's
5
+ * directory and the test setup's (runner, config, features) in the working directory.
5
6
  */
6
7
  import fs from 'node:fs';
7
8
  import net from 'node:net';
@@ -10,11 +11,13 @@ import path from 'node:path';
10
11
  import type { QuiescoConfig } from '@quiesco/core';
11
12
  import { loadConfig, serverPort } from '@quiesco/core';
12
13
 
14
+ import { APP_DIR_OPTION, appContext, inApp } from '../app-dir.js';
13
15
  import type { CliContext, CliPlatform } from '../context.js';
14
16
  import { PLATFORMS, parsePlatform, takeOption } from '../context.js';
15
17
  import { MIN_EXPO_SDK, UPGRADE_SDK_FIX, expoSdk } from '../expo-sdk.js';
16
18
  import { CLI_COMMANDS, installedVersion, isQuiescoPackage, scriptCommands } from '../packages.js';
17
19
  import { rootSourceFiles } from '../project.js';
20
+ import { RUNNER_PACKAGES, projectRunner } from '../runner.js';
18
21
 
19
22
  /** `info`: worth knowing, nothing is wrong (counted neither as a warning nor as a failure). */
20
23
  export type CheckStatus = 'ok' | 'info' | 'warn' | 'fail';
@@ -82,27 +85,46 @@ function expoCheck(ctx: CliContext, pkg: PackageJson): CheckResult {
82
85
  return sdk.sdk >= MIN_EXPO_SDK ? { name: 'Expo project', status: 'ok', detail } : { name: 'Expo project', status: 'fail', detail, fix: UPGRADE_SDK_FIX };
83
86
  }
84
87
 
85
- function projectChecks(ctx: CliContext): CheckResult[] {
88
+ /**
89
+ * The app (expo, @quiesco/agent, config plugin, Metro, entry) in `app`, the test setup (runner packages,
90
+ * older inits' files) in `ctx`: the same directory unless appDir is set (issue #54).
91
+ */
92
+ function projectChecks(ctx: CliContext, app: CliContext): CheckResult[] {
86
93
  const results: CheckResult[] = [];
87
- const pkg = readJson<PackageJson>(ctx, path.join(ctx.cwd, 'package.json'));
94
+ const separate = app !== ctx;
95
+ const pkg = readJson<PackageJson>(app, path.join(app.cwd, 'package.json'));
88
96
  if (pkg === null) {
89
- return [{ name: 'project', status: 'fail', detail: `no package.json in ${ctx.cwd}`, fix: 'Run quiesco in the Expo app directory.' }];
97
+ return [
98
+ {
99
+ name: 'project',
100
+ status: 'fail',
101
+ detail: `no package.json in ${app.cwd}`,
102
+ fix: separate ? 'appDir (quiesco.config) or --app-dir must name the Expo app\'s directory.' : 'Run quiesco in the Expo app directory, or set appDir in quiesco.config to where the app is.',
103
+ },
104
+ ];
90
105
  }
91
- results.push(expoCheck(ctx, pkg));
92
- const missing = ['@quiesco/agent', '@quiesco/cucumber', '@cucumber/cucumber'].filter((d) => !hasDep(pkg, d));
106
+ const testPkg = separate ? readJson<PackageJson>(ctx, path.join(ctx.cwd, 'package.json')) : pkg;
107
+ results.push(expoCheck(app, pkg));
108
+ // The app has the agent; the test project has the runner the commands use without --runner, with
109
+ // Quiesco's integration and the runner itself.
110
+ const runnerPkgs = RUNNER_PACKAGES[projectRunner(ctx)];
111
+ const missing = [
112
+ ...(hasDep(pkg, '@quiesco/agent') ? [] : [`@quiesco/agent${separate ? ` (in ${inApp(ctx, app)})` : ''}`]),
113
+ ...runnerPkgs.filter((d) => testPkg === null || !hasDep(testPkg, d)),
114
+ ];
93
115
  results.push(
94
116
  missing.length === 0
95
- ? { name: 'Quiesco packages', status: 'ok', detail: '@quiesco/agent, @quiesco/cucumber, @cucumber/cucumber' }
117
+ ? { name: 'Quiesco packages', status: 'ok', detail: ['@quiesco/agent', ...runnerPkgs].join(', ') }
96
118
  : { name: 'Quiesco packages', status: 'fail', detail: `missing ${missing.join(', ')}`, fix: 'Run `npx quiesco init`, or install them.' },
97
119
  );
98
120
 
99
- results.push(...versionChecks(ctx, pkg));
121
+ results.push(...versionChecks(ctx, [{ ctx: app, pkg }, ...(separate && testPkg !== null ? [{ ctx, pkg: testPkg }] : [])]));
100
122
  results.push(...legacyChecks(ctx));
101
123
 
102
- const appJson = readJson<{ expo?: { plugins?: unknown[] } }>(ctx, path.join(ctx.cwd, 'app.json'));
124
+ const appJson = readJson<{ expo?: { plugins?: unknown[] } }>(app, path.join(app.cwd, 'app.json'));
103
125
  const plugins = appJson?.expo?.plugins ?? [];
104
126
  const listed = plugins.some((p) => p === '@quiesco/expo-plugin' || (Array.isArray(p) && p[0] === '@quiesco/expo-plugin'));
105
- const dynamic = ['app.config.ts', 'app.config.js', 'app.config.mjs'].some((f) => ctx.exists(path.join(ctx.cwd, f)));
127
+ const dynamic = ['app.config.ts', 'app.config.js', 'app.config.mjs'].some((f) => app.exists(path.join(app.cwd, f)));
106
128
  results.push(
107
129
  listed
108
130
  ? { name: 'config plugin', status: 'ok', detail: '@quiesco/expo-plugin in app.json' }
@@ -111,8 +133,8 @@ function projectChecks(ctx: CliContext): CheckResult[] {
111
133
  : { name: 'config plugin', status: 'warn', detail: '@quiesco/expo-plugin is not in app.json plugins', fix: 'Add "@quiesco/expo-plugin" to expo.plugins (needed for iOS / Android e2e builds, not for web).' },
112
134
  );
113
135
 
114
- const metro = ['metro.config.js', 'metro.config.cjs', 'metro.config.mjs', 'metro.config.ts'].map((f) => path.join(ctx.cwd, f)).find((f) => ctx.exists(f));
115
- const metroSrc = metro !== undefined ? ctx.readFile(metro) : null;
136
+ const metro = ['metro.config.js', 'metro.config.cjs', 'metro.config.mjs', 'metro.config.ts'].map((f) => path.join(app.cwd, f)).find((f) => app.exists(f));
137
+ const metroSrc = metro !== undefined ? app.readFile(metro) : null;
116
138
  results.push(
117
139
  metroSrc !== null && metroSrc.includes('withQuiesco')
118
140
  ? { name: 'Metro', status: 'ok', detail: `${path.basename(metro as string)} uses withQuiesco()` }
@@ -133,8 +155,8 @@ function projectChecks(ctx: CliContext): CheckResult[] {
133
155
  fix: "Create index.ts with `import '@quiesco/agent';` as the first line followed by the original entry (e.g. `import 'expo-router/entry';`), and set \"main\": \"index.ts\".",
134
156
  });
135
157
  } else {
136
- const entry = [main, `${main}.ts`, `${main}.tsx`, `${main}.js`].map((f) => path.join(ctx.cwd, f)).find((f) => ctx.exists(f));
137
- const src = entry !== undefined ? ctx.readFile(entry) : null;
158
+ const entry = [main, `${main}.ts`, `${main}.tsx`, `${main}.js`].map((f) => path.join(app.cwd, f)).find((f) => app.exists(f));
159
+ const src = entry !== undefined ? app.readFile(entry) : null;
138
160
  const first = src !== null ? firstImport(src) : null;
139
161
  results.push(
140
162
  first === '@quiesco/agent'
@@ -149,13 +171,18 @@ function projectChecks(ctx: CliContext): CheckResult[] {
149
171
 
150
172
  /**
151
173
  * Issue #17: every Quiesco package in package.json is installed at one version, and every `quiesco <cmd>`
152
- * in the scripts exists in it.
174
+ * in the scripts exists in it. With appDir (issue #54) the app's and the test project's packages together.
153
175
  */
154
- function versionChecks(ctx: CliContext, pkg: PackageJson): CheckResult[] {
176
+ function versionChecks(ctx: CliContext, projects: readonly { ctx: CliContext; pkg: PackageJson }[]): CheckResult[] {
155
177
  const results: CheckResult[] = [];
156
- const names = [...new Set([...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})])].filter(isQuiescoPackage).sort();
178
+ const declared = projects.flatMap((p) =>
179
+ [...new Set([...Object.keys(p.pkg.dependencies ?? {}), ...Object.keys(p.pkg.devDependencies ?? {})])].filter(isQuiescoPackage).map((name) => ({ name, dir: p.ctx })),
180
+ );
181
+ const names = [...new Set(declared.map((d) => d.name))].sort();
157
182
  if (names.length === 0) return results;
158
- const installed = names.map((name) => ({ name, version: installedVersion(ctx, name) }));
183
+ const installed = declared
184
+ .sort((a, b) => a.name.localeCompare(b.name))
185
+ .map((d) => ({ name: d.dir === ctx ? d.name : `${d.name} (${inApp(ctx, d.dir)})`, version: installedVersion(d.dir, d.name) }));
159
186
  const missing = installed.filter((p) => p.version === null).map((p) => p.name);
160
187
  const versions = [...new Set(installed.flatMap((p) => (p.version !== null ? [p.version] : [])))];
161
188
  const list = installed.map((p) => `${p.name} ${p.version ?? '(not installed)'}`).join(', ');
@@ -183,7 +210,7 @@ function versionChecks(ctx: CliContext, pkg: PackageJson): CheckResult[] {
183
210
  },
184
211
  );
185
212
  }
186
- const unknown = scriptCommands(pkg.scripts).filter((c) => !(CLI_COMMANDS as readonly string[]).includes(c.command));
213
+ const unknown = projects.flatMap((p) => scriptCommands(p.pkg.scripts)).filter((c) => !(CLI_COMMANDS as readonly string[]).includes(c.command));
187
214
  if (unknown.length > 0) {
188
215
  results.push({
189
216
  name: 'scripts',
@@ -264,7 +291,7 @@ interface AppJsonIds {
264
291
  * uses) and, when they exist, with the prebuilt Android project and the iOS build. Placeholders left by
265
292
  * init fail.
266
293
  */
267
- async function appIdChecks(ctx: CliContext, config: QuiescoConfig): Promise<CheckResult[]> {
294
+ async function appIdChecks(ctx: CliContext, app: CliContext, config: QuiescoConfig): Promise<CheckResult[]> {
268
295
  const { ios, android } = config.apps;
269
296
  if (ios === undefined && android === undefined) return [];
270
297
  const configFile = CONFIG_FILES.find((f) => ctx.exists(path.join(ctx.cwd, f)));
@@ -279,12 +306,12 @@ async function appIdChecks(ctx: CliContext, config: QuiescoConfig): Promise<Chec
279
306
  },
280
307
  ];
281
308
  }
282
- const dynamic = DYNAMIC_APP_CONFIGS.find((f) => ctx.exists(path.join(ctx.cwd, f)));
309
+ const dynamic = DYNAMIC_APP_CONFIGS.find((f) => app.exists(path.join(app.cwd, f)));
283
310
  const results: CheckResult[] = [];
284
311
  if (dynamic !== undefined) {
285
312
  results.push({ name: 'app IDs', status: 'warn', detail: `${dynamic} found; cannot compare the app IDs with it`, fix: 'Make sure apps.ios.bundleId, apps.android.package and devClient.scheme are the values your app config sets.' });
286
313
  } else {
287
- const expo = readJson<AppJsonIds>(ctx, path.join(ctx.cwd, 'app.json'))?.expo ?? {};
314
+ const expo = readJson<AppJsonIds>(app, path.join(app.cwd, 'app.json'))?.expo ?? {};
288
315
  const schemes = expo.scheme === undefined ? [] : Array.isArray(expo.scheme) ? expo.scheme : [expo.scheme];
289
316
  const problems: string[] = [];
290
317
  const compare = (what: string, want: string, have: string | undefined): void => {
@@ -305,9 +332,9 @@ async function appIdChecks(ctx: CliContext, config: QuiescoConfig): Promise<Chec
305
332
  }
306
333
  // The builds: an app built before the IDs changed is another app.
307
334
  if (android !== undefined) {
308
- const gradle = ctx.readFile(path.join(ctx.cwd, 'android/app/build.gradle'));
335
+ const gradle = app.readFile(path.join(app.cwd, 'android/app/build.gradle'));
309
336
  const built = gradle === null ? undefined : /applicationId\s*(?:=\s*)?['"]([^'"]+)['"]/.exec(gradle)?.[1];
310
- const manifest = ctx.readFile(path.join(ctx.cwd, 'android/app/src/main/AndroidManifest.xml'));
337
+ const manifest = app.readFile(path.join(app.cwd, 'android/app/src/main/AndroidManifest.xml'));
311
338
  const scheme = android.devClient?.scheme;
312
339
  const wrong: string[] = [];
313
340
  if (built !== undefined && built !== android.package) wrong.push(`android/app/build.gradle has applicationId ${built}`);
@@ -463,7 +490,7 @@ export const defaultDoctorDeps: DoctorDeps = {
463
490
  }),
464
491
  };
465
492
 
466
- export async function runChecks(ctx: CliContext, only: CliPlatform | undefined, deps: DoctorDeps = defaultDoctorDeps): Promise<CheckResult[]> {
493
+ export async function runChecks(ctx: CliContext, only: CliPlatform | undefined, deps: DoctorDeps = defaultDoctorDeps, appDirFlag?: string): Promise<CheckResult[]> {
467
494
  const results: CheckResult[] = [];
468
495
  const major = Number.parseInt(ctx.nodeVersion, 10);
469
496
  results.push(
@@ -481,17 +508,27 @@ export async function runChecks(ctx: CliContext, only: CliPlatform | undefined,
481
508
  fix: 'Metro started with CI set does not watch files, so code changes do not reach the app under test. Unset it (unset CI) before EXPO_PUBLIC_QUIESCO=1 npx expo start.',
482
509
  });
483
510
  }
484
- results.push(...projectChecks(ctx));
485
- results.push(rootCheck(ctx, readJson<PackageJson>(ctx, path.join(ctx.cwd, 'package.json'))?.main));
486
-
511
+ // The config first: its appDir says where the app is (issue #54).
487
512
  let config: QuiescoConfig | null = null;
513
+ let configError: string | null = null;
488
514
  try {
489
515
  config = await deps.loadConfig(ctx.cwd);
490
- results.push({ name: 'quiesco.config', status: 'ok', detail: `apps: ${Object.keys(config.apps).join(', ') || 'none'}` });
491
- results.push(...(await appIdChecks(ctx, config)));
492
- results.push(...buildScriptChecks(readJson<PackageJson>(ctx, path.join(ctx.cwd, 'package.json')), config));
493
516
  } catch (e) {
494
- results.push({ name: 'quiesco.config', status: 'fail', detail: (e as Error).message.split('\n')[0] ?? '', fix: 'Create quiesco.config.mts (npx quiesco init writes one).' });
517
+ configError = (e as Error).message.split('\n')[0] ?? '';
518
+ }
519
+ const app = appContext(ctx, config, appDirFlag);
520
+ if (app !== ctx) results.push({ name: 'app', status: 'ok', detail: `${inApp(ctx, app)} (${appDirFlag !== undefined ? APP_DIR_OPTION : 'appDir'}); the test setup in ${ctx.cwd}` });
521
+ results.push(...projectChecks(ctx, app));
522
+ results.push(rootCheck(app, readJson<PackageJson>(app, path.join(app.cwd, 'package.json'))?.main));
523
+
524
+ if (config !== null) {
525
+ results.push({ name: 'quiesco.config', status: 'ok', detail: `apps: ${Object.keys(config.apps).join(', ') || 'none'}` });
526
+ results.push(...(await appIdChecks(ctx, app, config)));
527
+ // A script that builds may be in either package.json.
528
+ const scripts = { ...readJson<PackageJson>(app, path.join(app.cwd, 'package.json'))?.scripts, ...readJson<PackageJson>(ctx, path.join(ctx.cwd, 'package.json'))?.scripts };
529
+ results.push(...buildScriptChecks({ scripts }, config));
530
+ } else {
531
+ results.push({ name: 'quiesco.config', status: 'fail', detail: configError ?? '', fix: 'Create quiesco.config.mts (npx quiesco init writes one), in the test project when the app is elsewhere (appDir).' });
495
532
  }
496
533
 
497
534
  const platforms = only !== undefined ? [only] : PLATFORMS.filter((p) => config?.apps[p] !== undefined);
@@ -509,12 +546,13 @@ export async function runChecks(ctx: CliContext, only: CliPlatform | undefined,
509
546
  }
510
547
 
511
548
  export async function doctorCommand(args: readonly string[], ctx: CliContext, deps: DoctorDeps = defaultDoctorDeps): Promise<number> {
512
- const { value, rest } = takeOption(args, '--platform');
513
- if (rest.length > 0) {
514
- ctx.err(`quiesco doctor: unknown arguments ${rest.join(' ')}`);
549
+ const { value, rest: afterPlatform } = takeOption(args, '--platform');
550
+ const appDir = takeOption(afterPlatform, APP_DIR_OPTION);
551
+ if (appDir.rest.length > 0) {
552
+ ctx.err(`quiesco doctor: unknown arguments ${appDir.rest.join(' ')}`);
515
553
  return 2;
516
554
  }
517
- const results = await runChecks(ctx, parsePlatform(value), deps);
555
+ const results = await runChecks(ctx, parsePlatform(value), deps, appDir.value);
518
556
  for (const r of results) {
519
557
  ctx.out(`${ICON[r.status]} ${r.name}: ${r.detail}`);
520
558
  if (r.fix !== undefined && r.status !== 'ok') ctx.out(` → ${r.fix}`);
@@ -1,6 +1,7 @@
1
1
  /**
2
- * `quiesco init [--platforms ios,android,web] [--packages <dir>] [--skip-install]` (requirements.md
3
- * §6.12): set Quiesco up in an Expo project. Every step says what it did; existing files are never
2
+ * `quiesco init [--platforms ios,android,web] [--runner vitest|jest|cucumber] [--packages <dir>] [--skip-install]`
3
+ * (requirements.md §6.12): set Quiesco up in an Expo project. Without `--runner` it asks which test runner
4
+ * to use when a person is at the terminal, and takes Vitest otherwise. Every step says what it did; existing files are never
4
5
  * overwritten — when one needs a change Quiesco cannot make safely, the step prints what to add.
5
6
  *
6
7
  * `--packages <dir>`: install Quiesco from the tarballs in <dir> (`pnpm pack` output) instead of the
@@ -13,7 +14,9 @@ import { PLATFORMS, takeFlag, takeOption } from '../context.js';
13
14
  import { MIN_EXPO_SDK, UPGRADE_SDK_FIX, expoSdk } from '../expo-sdk.js';
14
15
  import { entryFile, registeredRoot, rootSourceFiles, wrapRegisteredRoot } from '../project.js';
15
16
  import type { AppJson, InitStep, PackageJson, StepLog } from '../setup-steps.js';
16
- import { DEV, RUNTIME, WEB_DEV, detectPackageManager, ensureAppIds, ensureScripts, ensureTsconfig, firstScheme, installPackages, printSteps, readJson, writeJson } from '../setup-steps.js';
17
+ import type { RunnerName } from '../runner.js';
18
+ import { RUNNER_LABELS, RUNNER_NAMES, RUNNER_PACKAGES, isRunnerName } from '../runner.js';
19
+ import { DEV, RUNTIME, WEB_DEV, detectPackageManager, ensureAppIds, ensureScripts, ensureTsconfig, execBin, firstScheme, installPackages, printSteps, readJson, runScript, writeJson } from '../setup-steps.js';
17
20
  import { upgradeCommand } from './upgrade.js';
18
21
 
19
22
  export { detectPackageManager, findTarballs } from '../setup-steps.js';
@@ -125,6 +128,55 @@ Then('the home screen is visible', async function (this: QuiescoWorld) {
125
128
  });
126
129
  `;
127
130
 
131
+ const VITEST_CONFIG = `// Quiesco's e2e tests. quiesco(): one app session per worker, kept across files, run one file at a time
132
+ // (quiesco({ workers: N }) runs them on N devices); the platform tags (@ios, @android, @web …).
133
+ // quiescoPlugin(): the run's progress for \`quiesco test\` and \`quiesco ui\`.
134
+ import { quiesco, quiescoPlugin } from '@quiesco/vitest/config';
135
+ import { defineConfig } from 'vitest/config';
136
+
137
+ export default defineConfig({
138
+ plugins: [quiescoPlugin()],
139
+ test: {
140
+ ...quiesco(),
141
+ include: ['e2e/**/*.test.ts'],
142
+ // Hooks shared by every test file (test.beforeEach …) go in a setup file: a module imported by several
143
+ // files runs once per worker (files share their modules), so its hooks would only apply to the first.
144
+ // setupFiles: ['e2e/setup.ts'],
145
+ },
146
+ });
147
+ `;
148
+
149
+ const VITEST_TEST = `import { test } from '@quiesco/vitest';
150
+
151
+ // Tests talk to the app through the \`app\` fixture and never wait or sleep: every call waits for the app
152
+ // to become idle first. Give the element testID="home" (or change the id here).
153
+ test('the home screen is shown', async ({ app }) => {
154
+ await app.expectVisible({ id: 'home' });
155
+ });
156
+ `;
157
+
158
+ const JEST_CONFIG = `// Quiesco's e2e tests. The preset: the Quiesco test environment (the global \`quiesco\`) and the reporter for
159
+ // \`quiesco test\` / \`quiesco ui\`. maxWorkers: N runs the files on N devices; testTimeout covers Quiesco's waits.
160
+ module.exports = {
161
+ preset: '@quiesco/jest',
162
+ rootDir: __dirname,
163
+ testMatch: ['<rootDir>/e2e/**/*.test.js'],
164
+ transform: {},
165
+ maxWorkers: 1,
166
+ testTimeout: 120_000,
167
+ };
168
+ `;
169
+
170
+ const JEST_TEST = `// Tests talk to the app through quiesco.app and never wait or sleep: every call waits for the app to
171
+ // become idle first. Give the element testID="home" (or change the id here).
172
+ test('the home screen is shown', async () => {
173
+ await quiesco.app.expectVisible({ id: 'home' });
174
+ });
175
+ `;
176
+
177
+ const VITEST_CONFIGS = ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs'].map((e) => `vitest.config.${e}`);
178
+ const JEST_CONFIGS = ['js', 'ts', 'mjs', 'cjs', 'json'].map((e) => `jest.config.${e}`);
179
+
128
180
  export async function initCommand(args: readonly string[], ctx: CliContext): Promise<number> {
129
181
  if (args.includes('--upgrade')) return upgradeCommand(args.filter((a) => a !== '--upgrade'), ctx);
130
182
  let rest = [...args];
@@ -134,10 +186,16 @@ export async function initCommand(args: readonly string[], ctx: CliContext): Pro
134
186
  rest = packagesOpt.rest;
135
187
  const skipInstall = takeFlag(rest, '--skip-install');
136
188
  rest = skipInstall.rest;
189
+ const runnerOpt = takeOption(rest, '--runner');
190
+ rest = runnerOpt.rest;
137
191
  if (rest.length > 0) {
138
192
  ctx.err(`quiesco init: unknown arguments ${rest.join(' ')}`);
139
193
  return 2;
140
194
  }
195
+ if (runnerOpt.value !== undefined && !isRunnerName(runnerOpt.value)) {
196
+ ctx.err(`quiesco init: unknown runner "${runnerOpt.value}" (${RUNNER_NAMES.join(', ')}).`);
197
+ return 2;
198
+ }
141
199
 
142
200
  const pkgFile = path.join(ctx.cwd, 'package.json');
143
201
  const pkg = readJson<PackageJson>(ctx, pkgFile);
@@ -156,13 +214,24 @@ export async function initCommand(args: readonly string[], ctx: CliContext): Pro
156
214
  })
157
215
  : ['ios', 'android', ...(hasWebDeps ? (['web'] as const) : [])];
158
216
 
217
+ const runner: RunnerName =
218
+ runnerOpt.value !== undefined
219
+ ? (runnerOpt.value as RunnerName)
220
+ : ctx.interactive
221
+ ? ((await ctx.choose(
222
+ 'Which test runner should drive Quiesco?',
223
+ RUNNER_NAMES.map((r) => ({ value: r, label: RUNNER_LABELS[r] })),
224
+ 'vitest',
225
+ )) as RunnerName)
226
+ : 'vitest';
227
+
159
228
  const steps: InitStep[] = [];
160
229
  const log: StepLog = { ctx, steps, dryRun: false };
161
230
  const pm = detectPackageManager(ctx);
162
231
 
163
232
  // 1. Dependencies.
164
233
  const runtime = [...RUNTIME];
165
- const dev = [...DEV, ...(platforms.includes('web') ? WEB_DEV : [])];
234
+ const dev = [...DEV, ...RUNNER_PACKAGES[runner], ...(platforms.includes('web') ? WEB_DEV : [])];
166
235
  const installed = await installPackages(log, {
167
236
  pm,
168
237
  runtime,
@@ -250,7 +319,7 @@ export async function initCommand(args: readonly string[], ctx: CliContext): Pro
250
319
  }
251
320
  }
252
321
 
253
- // 5. quiesco.config.mts (.mts: an ES module whatever package.json says), cucumber config, features.
322
+ // 5. quiesco.config.mts (.mts: an ES module whatever package.json says), the runner's config, a first test.
254
323
  const write = (rel: string, content: string, note: string, alternatives: readonly string[] = [rel]): void => {
255
324
  const existing = alternatives.find((f) => ctx.exists(path.join(ctx.cwd, f)));
256
325
  if (existing !== undefined) {
@@ -261,17 +330,32 @@ export async function initCommand(args: readonly string[], ctx: CliContext): Pro
261
330
  steps.push({ status: 'created', what: rel, note });
262
331
  };
263
332
  write('quiesco.config.mts', quiescoConfig(appWithIds, platforms), `apps: ${platforms.join(', ')}`, ['quiesco.config.ts', 'quiesco.config.mts', 'quiesco.config.js', 'quiesco.config.mjs']);
264
- write('cucumber.mjs', CUCUMBER_CONFIG, 'step files and format (features/**/*.feature by default)', ['cucumber.mjs', 'cucumber.js', 'cucumber.cjs', 'cucumber.json', 'cucumber.yaml', 'cucumber.yml']);
265
- write('features/package.json', '{ "type": "module" }\n', 'step files are ES modules');
266
- write('features/support/quiesco.ts', SUPPORT, 'this.app and the lifecycle hooks');
267
- write('features/app.feature', FEATURE, 'a first scenario');
268
- write('features/step_definitions/app.steps.ts', STEPS, 'its step');
333
+ /** A config of the runner's own name may be the unit tests': then Quiesco's goes next to it and the scripts name it. */
334
+ let testArgs = '';
335
+ let firstTest: string;
336
+ if (runner === 'cucumber') {
337
+ write('cucumber.mjs', CUCUMBER_CONFIG, 'step files and format (features/**/*.feature by default)', ['cucumber.mjs', 'cucumber.js', 'cucumber.cjs', 'cucumber.json', 'cucumber.yaml', 'cucumber.yml']);
338
+ write('features/package.json', '{ "type": "module" }\n', 'step files are ES modules');
339
+ write('features/support/quiesco.ts', SUPPORT, 'this.app and the lifecycle hooks');
340
+ write('features/app.feature', FEATURE, 'a first scenario');
341
+ write('features/step_definitions/app.steps.ts', STEPS, 'its step');
342
+ firstTest = 'features/step_definitions/app.steps.ts';
343
+ } else {
344
+ const [names, standard, e2eName, content] =
345
+ runner === 'vitest' ? [VITEST_CONFIGS, 'vitest.config.mts', 'vitest.e2e.config.mts', VITEST_CONFIG] : [JEST_CONFIGS, 'jest.config.cjs', 'jest.e2e.config.cjs', JEST_CONFIG];
346
+ const own = names.find((f) => ctx.exists(path.join(ctx.cwd, f))) ?? (runner === 'jest' && latest.jest !== undefined ? 'package.json "jest"' : undefined);
347
+ const configFile = own === undefined ? standard : e2eName;
348
+ write(configFile, content, own === undefined ? 'Quiesco for the e2e tests in e2e/' : `next to ${own} (your unit tests'); the e2e scripts pass --config ${e2eName}`);
349
+ if (own !== undefined) testArgs = `--config ${configFile}`;
350
+ firstTest = runner === 'vitest' ? 'e2e/app.test.ts' : 'e2e/app.test.js';
351
+ write(firstTest, runner === 'vitest' ? VITEST_TEST : JEST_TEST, 'a first test');
352
+ }
269
353
 
270
354
  // 5b. tsconfig.json (issue #21): step files import each other with .ts (Node's type stripping needs it).
271
- ensureTsconfig(log);
355
+ if (runner === 'cucumber') ensureTsconfig(log);
272
356
 
273
357
  // 6. Scripts.
274
- ensureScripts(log, platforms);
358
+ ensureScripts(log, platforms, testArgs);
275
359
 
276
360
  printSteps(ctx, steps);
277
361
  ctx.out('');
@@ -281,10 +365,12 @@ export async function initCommand(args: readonly string[], ctx: CliContext): Pro
281
365
  if (!rootSourceFiles(ctx, finalMain).some((f) => (ctx.readFile(f) ?? '').includes('QuiescoRoot'))) {
282
366
  next.push("Wrap the root layout in <QuiescoRoot> (import { QuiescoRoot } from '@quiesco/agent'): the app connects to Quiesco from it, and the soft reset remounts it.");
283
367
  }
284
- next.push('Give the home screen testID="home" (features/step_definitions/app.steps.ts looks for it).');
285
- if (platforms.includes('web')) next.push('npx playwright install chromium, then npm run e2e:web');
368
+ next.push(`Give the home screen testID="home" (${firstTest} looks for it).`);
369
+ if (platforms.includes('web')) next.push(`${execBin(pm, 'playwright install chromium')}, then ${runScript(pm, 'e2e:web')}`);
286
370
  next.forEach((line, i) => ctx.out(` ${i + 1}. ${line}`));
287
- if (platforms.some((p) => p !== 'web')) ctx.out(' • iOS / Android: npm run e2e:build:ios (or :android) builds the app into binaryPath, then npm run e2e:ios; quiesco test starts Metro when it is not running. `npx quiesco doctor` checks the setup.');
371
+ if (platforms.some((p) => p !== 'web')) {
372
+ ctx.out(` • iOS / Android: ${runScript(pm, 'e2e:build:ios')} (or :android) builds the app into binaryPath, then ${runScript(pm, 'e2e:ios')}; quiesco test starts Metro when it is not running. \`${execBin(pm, 'quiesco doctor')}\` checks the setup.`);
373
+ }
288
374
  ctx.out(' • A SYNC_TIMEOUT that names a decorative animation (the default template spins a glow): give it a testID and add it to sync.ignoreElements.');
289
375
  return 0;
290
376
  }
@@ -9,13 +9,15 @@ import { listTests } from '@quiesco/core';
9
9
 
10
10
  import type { CliContext } from '../context.js';
11
11
  import { takeFlag, takeOption } from '../context.js';
12
+ import { projectRunner } from '../runner.js';
12
13
 
13
14
  export const LIST_HELP = `Usage: quiesco list [options] [runner arguments…]
14
15
 
15
16
  Lists the tests the runner would run, without running them (no device is started).
16
17
 
17
18
  Options:
18
- --runner cucumber|jest|vitest Test runner (default: cucumber)
19
+ --runner cucumber|jest|vitest Test runner (default: the one whose @quiesco package
20
+ is installed; cucumber when several or none are)
19
21
  --json Print the list as JSON (ids as in the run events)
20
22
  -h, --help Show this help
21
23
 
@@ -53,7 +55,7 @@ export async function listCommand(args: readonly string[], ctx: CliContext, deps
53
55
  }
54
56
  const r = takeOption(args, '--runner');
55
57
  const json = takeFlag(r.rest, '--json');
56
- const runner = r.value ?? 'cucumber';
58
+ const runner = r.value ?? projectRunner(ctx);
57
59
  if (!(RUNNERS as readonly string[]).includes(runner)) {
58
60
  ctx.err(`quiesco list: unknown runner "${runner}" (cucumber, jest or vitest).`);
59
61
  return 2;