feat: ns compiled verify compares a compiled release with its JavaScript release

Builds both releases of the project, then runs the project's @nativescript/compiler ns-compiled-verify on them:
the same steps (the project's verify.json, or a shot after launch) on one iOS Simulator, compared pixel by pixel,
failing where a screenshot differs or an app stops running.

Author: NathanWalker

docs/man_pages/project/testing/compiled-verify.md

@@ -0,0 +1,46 @@
+<% if (isJekyll) { %>---
+title: ns compiled verify
+position: 20
+---<% } %>
+
+# ns compiled verify
+
+### Description
+
+Builds the project's JavaScript release and its compiled release (`--compiled`), runs both the same way on one iOS Simulator and compares them: a screenshot of each step, pixel by pixel, and whether either app stops running. Use it before shipping a compiled release.
+
+The steps are the project's `verify.json`, when it has one. Each screen launches the app afresh; coordinates are points on the simulator's screen:
+
+```json
+{
+  "screens": [
+    { "name": "home", "steps": [["shot", "start"], ["tap", 200, 400], ["wait", 1], ["type", "Ada"], ["shot", "typed"]] }
+  ]
+}
+```
+
+Steps: `shot <name>`, `tap <x> <y> [seconds held]`, `taps <x> <y> [count]`, `swipe <x> <y> <toX> <toY>`, `drag <x> <y> <toX> <toY> [seconds]`, `type <text>`, `wait <seconds>`, `openurl <url>`. Without `verify.json`, the app is compared once it settles after launch.
+
+The screenshots and `report.json` are written to `platforms/compiled/verify`. The command fails when a screenshot differs or an app stops running.
+
+<% if(isConsole && (isWindows || isLinux)) { %>WARNING: You can run this command only on macOS systems.<% } %>
+
+### Commands
+
+Usage | Synopsis
+---|---
+General | `$ ns compiled verify [ios]`
+
+### Prerequisites
+
+* `@nativescript/compiler` as a devDependency of the project.
+* Xcode with an iOS Simulator runtime.
+
+<% if(isHtml) { %>
+
+### Related Commands
+
+Command | Description
+----------|----------
+[build ios](build-ios.html) | Builds the project for iOS, `--compiled` to compile it to native code.
+<% } %>

lib/bootstrap.ts

@@ -184,6 +184,7 @@ injector.requireCommand("run|android", "./commands/run");
 injector.requireCommand("run|vision", "./commands/run");
 injector.requireCommand("run|visionos", "./commands/run");
 injector.requireCommand("typings", "./commands/typings");
+injector.requireCommand("compiled|verify", "./commands/compiled-verify");
 
 injector.requireCommand("preview", "./commands/preview");
 

lib/commands/compiled-verify.ts

@@ -0,0 +1,89 @@
+import * as path from "path";
+import { IChildProcess, IErrors, IFileSystem } from "../common/declarations";
+import { ICommand, ICommandParameter } from "../common/definitions/commands";
+import { injector } from "../common/yok";
+import { IProjectData } from "../definitions/project";
+import { CompiledReleaseService } from "../services/compiled-release-service";
+
+/**
+ * `ns compiled verify [ios]`: builds the JavaScript release and the compiled
+ * release of the project, runs both the same way on one simulator and compares
+ * them, a screenshot of each step pixel by pixel and whether either stops
+ * running. The steps are the project's `verify.json`, when it has one
+ * (`{ "screens": [{ "name": "home", "steps": [["shot", "start"], ["tap", 200, 400], ["shot", "tapped"]] }] }`);
+ * without it, a screenshot once the app settles.
+ */
+export class CompiledVerifyCommand implements ICommand {
+	public allowedParameters: ICommandParameter[] = [];
+
+	constructor(
+		private $childProcess: IChildProcess,
+		private $compiledReleaseService: CompiledReleaseService,
+		private $errors: IErrors,
+		private $fs: IFileSystem,
+		private $logger: ILogger,
+		private $projectData: IProjectData,
+	) {}
+
+	public async execute(args: string[]): Promise<void> {
+		const platform = (args[0] ?? "ios").toLowerCase();
+		if (platform !== "ios") {
+			this.$errors.fail(
+				"ns compiled verify compares iOS builds; Android is to follow.",
+			);
+		}
+		this.$projectData.initializeProjectData();
+		const projectDir = this.$projectData.projectDir;
+		const cli = process.argv[1];
+		const ns = (...buildArgs: string[]) =>
+			this.$childProcess.spawnFromEvent(
+				process.execPath,
+				[cli, "build", "ios", ...buildArgs],
+				"close",
+				{ cwd: projectDir, stdio: "inherit" },
+			);
+
+		this.$logger.info("Building the JavaScript release...");
+		await ns("--release", "--no-compiled");
+		this.$logger.info("Building the compiled release...");
+		await ns("--compiled");
+
+		const js = this.findApp(
+			path.join(this.$projectData.platformsDir, "ios", "build", "Release-iphonesimulator"),
+		);
+		const compiled = this.findApp(
+			path.join(this.$projectData.platformsDir, "compiled", "ios", "DerivedData", "Build", "Products", "Release-iphonesimulator"),
+		);
+		const steps = path.join(projectDir, "verify.json");
+		const out = path.join(this.$projectData.platformsDir, "compiled", "verify");
+		const verify = this.$compiledReleaseService.getCompilerBin(
+			this.$projectData,
+			"ns-compiled-verify",
+		);
+		try {
+			await this.$childProcess.spawnFromEvent(
+				process.execPath,
+				[verify, "--js", js, "--compiled", compiled, "--out", out, ...(this.$fs.exists(steps) ? ["--steps", steps] : [])],
+				"close",
+				{ cwd: projectDir, stdio: "inherit" },
+			);
+		} catch {
+			this.$errors.fail(
+				`The compiled release differs from its JavaScript release: see ${out}`,
+			);
+		}
+	}
+
+	private findApp(dir: string): string {
+		const app = this.$fs.exists(dir)
+			? this.$fs.readDirectory(dir).find((f) => f.endsWith(".app"))
+			: undefined;
+		if (!app) {
+			this.$errors.fail(`No simulator build in ${dir}.`);
+		}
+
+		return path.join(dir, app);
+	}
+}
+
+injector.registerCommand("compiled|verify", CompiledVerifyCommand);

lib/services/compiled-release-service.ts

@@ -142,10 +142,20 @@ export class CompiledReleaseService {
 	}
 
 	private getCompilerPath(projectData: IProjectData): string {
+		return this.getCompilerBin(projectData, "ns-native");
+	}
+
+	/** A command of the project's `@nativescript/compiler` (`ns-native`, `ns-compiled-verify`), as a script for Node. */
+	public getCompilerBin(projectData: IProjectData, name: string): string {
 		const packageDir = this.getPackageDir(projectData);
 		const { bin } = this.$fs.readJson(path.join(packageDir, "package.json"));
+		if (!bin?.[name]) {
+			this.$errors.fail(
+				`The project's ${COMPILER_PACKAGE_NAME} has no ${name}: update it.`,
+			);
+		}
 
-		return path.join(packageDir, bin["ns-native"]);
+		return path.join(packageDir, bin[name]);
 	}
 
 	private getPackageDir(projectData: IProjectData): string {