Merge pull request #3307 from enquora/manual-tests-navigation-viewer

Manual tests navigation viewer
This commit is contained in:
David Richardson
2026-09-03 12:36:11 -06:00
committed by GitHub
7 changed files with 878 additions and 0 deletions
+2
View File
@@ -26,3 +26,5 @@ node_modules
/dist/cappuccino/package.json
/dist/cappuccino/lib
/dist/cappuccino/bin
Tests/Manual/.Frameworks
/Tests/Manual/index.html
+153
View File
@@ -0,0 +1,153 @@
/*
* Jakefile
* Tests/Manual
*
* Provisions ./Frameworks for every manual integration test app.
* See FRAMEWORKS-PROVISIONING-PLAN.md for the reasoning behind this design.
*
* Scope: this file only manages Frameworks symlinks. It does not build,
* run, or modify any individual test app.
*/
const path = require("path");
const fs = require("fs");
var ENV = process.env,
task = JAKE.task;
// Single source of truth for the merge: every app links to this, and
// this links into dist. A dist rebuild is then visible everywhere with
// no re-provisioning.
var SHARED_FRAMEWORKS = ".Frameworks";
// Left side: name under Tests/Manual/.Frameworks (and .../Debug).
// Right side: path under dist, relative to Tests/Manual.
var RELEASE_MEMBERS = {
"AppKit": path.join("..", "..", "dist", "cappuccino", "Frameworks", "AppKit"),
"BlendKit": path.join("..", "..", "dist", "cappuccino", "Frameworks", "BlendKit"),
"Foundation": path.join("..", "..", "dist", "cappuccino", "Frameworks", "Foundation"),
"Objective-J": path.join("..", "..", "dist", "objective-j", "Frameworks", "Objective-J")
};
var DEBUG_MEMBERS = {
"AppKit": path.join("..", "..", "dist", "cappuccino", "Frameworks", "Debug", "AppKit"),
"BlendKit": path.join("..", "..", "dist", "cappuccino", "Frameworks", "Debug", "BlendKit"),
"Foundation": path.join("..", "..", "dist", "cappuccino", "Frameworks", "Debug", "Foundation"),
"Objective-J": path.join("..", "..", "dist", "objective-j", "Frameworks", "Debug", "Objective-J")
};
// lstat, not stat -- a broken symlink must be seen as "exists, is a
// symlink", not thrown away as ENOENT.
function lstatOrNull(aPath)
{
try
{
return fs.lstatSync(aPath);
}
catch (e)
{
return null;
}
}
// Creates or repairs a single symlink. Safe to call every time: skips
// when the link is already correct, so a repeat `configure` costs one
// lstat and one readlink per member when nothing changed.
function ensureSymlink(linkPath, targetPath)
{
var desiredRelative = path.relative(path.dirname(linkPath), targetPath);
var info = lstatOrNull(linkPath);
if (info)
{
if (info.isSymbolicLink() && fs.readlinkSync(linkPath) === desiredRelative)
return;
if (info.isSymbolicLink())
fs.unlinkSync(linkPath);
else
{
console.log("configure: replacing non-symlink at " + linkPath);
fs.rmSync(linkPath, { recursive: true, force: true });
}
}
fs.symlinkSync(desiredRelative, linkPath, "dir");
}
function buildSharedFrameworks()
{
fs.mkdirSync(path.join(SHARED_FRAMEWORKS, "Debug"), { recursive: true });
Object.keys(RELEASE_MEMBERS).forEach(function(name)
{
ensureSymlink(path.join(SHARED_FRAMEWORKS, name), RELEASE_MEMBERS[name]);
});
Object.keys(DEBUG_MEMBERS).forEach(function(name)
{
ensureSymlink(path.join(SHARED_FRAMEWORKS, "Debug", name), DEBUG_MEMBERS[name]);
});
}
// An app directory is anything under Tests/Manual with Info.plist or
// index.html -- the same test migrate_jakefiles.py already uses to
// find app roots. Excludes the shared cache and any dotfile entries.
function listAppDirs()
{
return fs.readdirSync(".", { withFileTypes: true })
.filter(function(entry)
{
if (!entry.isDirectory())
return false;
if (entry.name.charAt(0) === ".")
return false;
return fs.existsSync(path.join(entry.name, "Info.plist")) ||
fs.existsSync(path.join(entry.name, "index.html"));
})
.map(function(entry) { return entry.name; });
}
function linkAllApps()
{
listAppDirs().forEach(function(appDir)
{
ensureSymlink(path.join(appDir, "Frameworks"), SHARED_FRAMEWORKS);
});
}
task ("refresh-dist", function()
{
JAKE.subjake(["../.."], "dist", ENV);
});
task ("configure", ["refresh-dist"], function()
{
buildSharedFrameworks();
linkAllApps();
});
task ("clean", function()
{
listAppDirs().forEach(function(appDir)
{
var linkPath = path.join(appDir, "Frameworks");
var info = lstatOrNull(linkPath);
if (!info)
return;
if (info.isSymbolicLink())
fs.unlinkSync(linkPath);
else
console.log("clean: skipping non-symlink at " + linkPath);
});
});
task ("clobber", ["clean"], function()
{
fs.rmSync(SHARED_FRAMEWORKS, { recursive: true, force: true });
});
task ("default", ["configure"]);
+34
View File
@@ -0,0 +1,34 @@
# Manual Integration Tests
This directory contains the manual integration test suite for Cappuccino.
Each subdirectory represents a distinct test application.
## Integration Test Definition
Unlike automated, isolated unit tests located in Tests/AppKit, Tests/Foundation, and Tests/Objective-J, the tests in this directory validate the framework as a complete, running application.
A test consists of a minimal Cappuccino application (AppController.j, main.j, Info.plist, index.html) executing in a real browser, exercising the compiled runtime, rendering pipeline, and target classes together.
These tests require manual verification. There are no automated assertions; a human reviewer must open the application, interact with it, and visually verify its behavior.
This suite is designed for human review of specific features, not yet unattended CI.
## Execution
Open /index.html (release) or /index-debug.html (debug, unminified) directly in a web browser.
No intermediate build step is required to load the framework and application sources, provided the /Frameworks directory exists.
To provision the Frameworks directory for every application in the suite, execute `jake configure` within Tests/Manual once initially, and after any framework modifications. The available tasks are:
- `configure:` (Default): Depends on refresh-dist. Builds a shared, merged .Frameworks cache once, then provisions every test application with a single symlink pointing to it.
- `refresh-dist`: Rebuilds the dist packages at the repository root (../../dist).
- `clean`: Removes the Frameworks symlink from each application directory without affecting actual directories. Skips any unmanaged, non-symlink directories.
- `clobber`: Executes clean, then removes the shared .Frameworks cache.
Many applications contain legacy Jakefiles predating the current Node-hosted toolchain.
These use incompatible idioms, will not execute correctly via per-application jake build or jake run commands, and are not required to open the tests directly in a browser. Migration of these Jakefiles is pending.
## Framework Provisioning
The HTML entry points load Frameworks/Objective-J/Objective-J.js (or the debug equivalent) via a literal relative path.
Without this directory present, the application will not load.
### Shared Cache Architecture
Cappuccino's framework build is distributed across two packages (dist/cappuccino, dist/objective-j) and two target levels (release, debug). Every application requires the same merged subset of eight items.
Utilizing a shared cache (.Frameworks) with per-application symlinks provides three structural advantages over copying or linking individual framework components directly into dist:
- **Centralized Configuration**: Modifying the required framework set requires only a single edit, which immediately updates all applications. Direct linking requires restating the set for every application.
- **Atomic Cleanup**: The clean operation targets a single symlink per application. Managing a per-application directory requires sweeping the directory and distinguishing managed components from unmanaged files.
- **Scalability**: The operational cost scales with the application count, rather than the product of application count and member count. Direct linking repeats eight operations per application on every configure execution, whereas the shared cache performs the operations once globally. This ensures configure remains fast enough to run reflexively during iterative development.
### Portability
The Frameworks symlink is ephemeral, ignored by git, and valid exclusively within the Tests/Manual tree.
To relocate a test, regenerate the Frameworks directory at the destination using `capp gen --frameworks appName` (or `--frameworks --symlink appName`), utilizing the binary located at dist/cappuccino/bin/capp.
+249
View File
File diff suppressed because one or more lines are too long
+114
View File
@@ -0,0 +1,114 @@
#!/usr/bin/env node
/*
* serve.js
* Tests/Manual
*
* Regenerates index.html, then serves this directory over plain HTTP,
* so tests run in any browser -- not only Safari via file://.
*
* No npm dependencies -- Node core modules only. Ctrl-C to stop.
*
* Writes ./index.html: links every manual test app's source entry
* points, plus its Build/Debug and Build/Release product entry
* points when they exist.
*
* No npm dependencies -- Node core modules only.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
const http = require("http");
const fs = require("fs");
const path = require("path");
const { exec } = require("child_process");
const { generateIndex } = require("./generate-index.js");
const ROOT = __dirname;
const PORT = 8347;
const MIME_TYPES = {
".html": "text/html",
".htm": "text/html",
".js": "application/javascript",
".sj": "application/javascript",
".css": "text/css",
".json": "application/json",
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".gif": "image/gif",
".svg": "image/svg+xml",
".txt": "text/plain",
".plist": "text/plain"
};
function resolveRequestPath(url)
{
var decoded = decodeURIComponent(url.split("?")[0]);
var resolved = path.normalize(path.join(ROOT, decoded));
// Reject traversal outside ROOT.
if (resolved !== ROOT && !resolved.startsWith(ROOT + path.sep))
return null;
return resolved;
}
function serveFile(filePath, res)
{
fs.readFile(filePath, function(err, data)
{
if (err)
{
res.writeHead(404, { "Content-Type": "text/plain" });
res.end("404 Not Found: " + filePath);
return;
}
var type = MIME_TYPES[path.extname(filePath).toLowerCase()] || "application/octet-stream";
res.writeHead(200, { "Content-Type": type });
res.end(data);
});
}
const server = http.createServer(function(req, res)
{
var filePath = resolveRequestPath(req.url);
if (!filePath)
{
res.writeHead(403, { "Content-Type": "text/plain" });
res.end("403 Forbidden");
return;
}
fs.stat(filePath, function(err, stats)
{
if (!err && stats.isDirectory())
filePath = path.join(filePath, "index.html");
serveFile(filePath, res);
});
});
generateIndex();
server.listen(PORT, function()
{
var url = "http://localhost:" + PORT + "/index.html";
console.log("Serving " + ROOT + " at " + url);
console.log("Ctrl-C to stop.");
exec("open " + url);
});
+326
View File
@@ -0,0 +1,326 @@
#!/usr/bin/env python3
"""
Migrate Cappuccino integration-test Jakefiles under Tests/Manual from the
Narwhal-hosted format to the Node-hosted format.
Each Jakefile is updated in place: the leading file-metadata comment block
at the top of the file is left untouched, and everything after it is fully
replaced with the non-metadata content of JakefileNew (the template),
substituted with per-app values.
Six lines are copied from the legacy file, each tested for existence
independently -- any that aren't present fall back to the template's own
literal default:
task.setProductName("capp-modernize");
task.setIdentifier("com.yourcompany.cappModernize");
task.setVersion("1.0");
task.setAuthor("Your Company");
task.setEmail("feedback @nospam@ yourcompany.com");
task.setSummary("capp-modernize");
Nothing else is extracted -- sources/resources/index/info-plist paths,
compiler flags, OBJJ_INCLUDE_PATHS, app-size tracking, task list, etc. all
come from the template unchanged.
The internal `projectName` variable (used in the app(...) call and all
build-path joins) is not one of the six copied fields -- it's taken from
the containing directory name, since it must be unique per app and the
old file's app(...) call is not reliably a string literal.
This is a full technical-debt pass: every Jakefile under the given root
is updated, including ones already hand-updated to Node idioms. Before
any file is overwritten, the original is copied to JakefileBackup in the
same directory.
Some test application directories have no Jakefile at all. These are
detected by the presence of Info.plist or index.html with no sibling
Jakefile, and are reported and skipped rather than guessed at.
Usage:
python3 migrate-jakefiles.py [--apply]
Default is a dry run: prints what would happen, writes nothing.
--apply performs the migration.
"""
import argparse
import re
import shutil
import sys
from pathlib import Path
from string import Template
HEADER_RE = re.compile(r'\A\s*/\*.*?\*/\s*', re.DOTALL)
FIELD_PATTERNS = {
"product_name": r'task\.setProductName\(\s*"([^"]*)"\s*\)',
"identifier": r'task\.setIdentifier\(\s*"([^"]*)"\s*\)',
"version": r'task\.setVersion\(\s*"([^"]*)"\s*\)',
"author": r'task\.setAuthor\(\s*"([^"]*)"\s*\)',
"email": r'task\.setEmail\(\s*"([^"]*)"\s*\)',
"summary": r'task\.setSummary\(\s*"([^"]*)"\s*\)',
}
# Literal defaults, taken verbatim from JakefileNew -- used only when the
# corresponding line is absent from the legacy file.
DEFAULTS = {
"product_name": "capp-modernize",
"identifier": "com.yourcompany.cappModernize",
"version": "1.0",
"author": "Your Company",
"email": "feedback @nospam@ yourcompany.com",
"summary": "capp-modernize",
}
# JakefileNew's non-metadata content, verbatim, with $-style placeholders
# for project_name (directory-derived) and the six copied fields.
BODY_TEMPLATE = Template('''const path = require("path");
const fs = require("fs");
var ENV = process.env,
task = JAKE.task,
FileList = JAKE.FileList,
app = CAPPUCCINO.Jake.applicationtask.app,
configuration = ENV["CONFIG"] || ENV["CONFIGURATION"] || ENV["c"] || "Debug",
OS = require("os"),
projectName = "$project_name",
productName = "$product_name";
var buildDir = path.resolve(ENV["BUILD_PATH"] || ENV["CAPP_BUILD"] || "Build");
app (projectName, function(task)
{
ENV["OBJJ_INCLUDE_PATHS"] = "Frameworks";
if (configuration === "Debug")
ENV["OBJJ_INCLUDE_PATHS"] = path.join(ENV["OBJJ_INCLUDE_PATHS"], configuration);
task.setBuildIntermediatesPath(path.join(buildDir, projectName + ".build", configuration));
task.setBuildPath(path.join(buildDir, configuration));
task.setProductName(productName);
task.setIdentifier("$identifier");
task.setVersion("$version");
task.setAuthor("$author");
task.setEmail("$email");
task.setSummary("$summary");
task.setSources(new FileList("**/*.j").exclude(path.join("Build", "**")).exclude(path.join("Frameworks", "Source", "**")));
task.setResources(new FileList("Resources/**"));
task.setIndexFilePath("index.html");
task.setInfoPlistPath("Info.plist");
if (configuration === "Debug")
task.setCompilerFlags("-DDEBUG -g -S --inline-msg-send");
else
task.setCompilerFlags("-O2");
});
task ("default", [projectName], function()
{
printResults(configuration);
});
task ("build", ["default"], function()
{
updateApplicationSize();
});
task ("debug", function()
{
configuration = ENV["CONFIGURATION"] = "Debug";
JAKE.subjake(["."], "build", ENV);
});
task ("release", function()
{
configuration = ENV["CONFIGURATION"] = "Release";
JAKE.subjake(["."], "build", ENV);
});
task ("run", ["debug"], function()
{
OS.system(["open", path.join(buildDir, "Debug", productName, "index.html")]);
});
task ("run-release", ["release"], function()
{
OS.system(["open", path.join(buildDir, "Release", productName, "index.html")]);
});
task ("deploy", ["release"], function()
{
FILE.mkdirs(path.join(buildDir, "Deployment", productName));
OS.system(["press", "-f", path.join(buildDir, "Release", productName), path.join(buildDir, "Deployment", productName)]);
printResults("Deployment")
});
function printResults(configuration)
{
console.log("----------------------------");
console.log(configuration+" app built at path: " + path.join(buildDir, configuration, productName));
console.log("----------------------------");
}
function updateApplicationSize()
{
console.log("Calculating application file sizes...");
var contents = fs.readFileSync(path.join(buildDir, configuration, productName, "Info.plist"), { encoding: "utf8" }),
format = CFPropertyList.sniffedFormatOfString(contents),
plist = CFPropertyList.propertyListFromString(contents),
totalBytes = {executable:0, data:0, mhtml:0};
// Get the size of all framework executables and sprite data
var frameworksDir = "Frameworks";
if (configuration === "Debug")
frameworksDir = path.join(frameworksDir, "Debug");
var frameworks = [];
if (fs.existsSync(frameworksDir)) {
frameworks = fs.readdirSync(frameworksDir);
}
frameworks.forEach(function(framework)
{
if (framework !== "Source")
addBundleFileSizes(path.join(frameworksDir, framework), totalBytes);
});
// Read in the default theme name, and attempt to get its size
var themeName = plist.valueForKey("CPDefaultTheme") || "Aristo2",
themePath = nil;
if (themeName === "Aristo" || themeName === "Aristo2")
themePath = path.join(frameworksDir, "AppKit", "Resources", themeName + ".blend");
else
themePath = path.join("Frameworks", "Resources", themeName + ".blend");
if (fs.existsSync(themePath) && fs.lstatSync(themePath).isDirectory())
addBundleFileSizes(themePath, totalBytes);
// Add sizes for the app
addBundleFileSizes(path.join(buildDir, configuration, productName), totalBytes);
console.log("Executables: " + totalBytes.executable + ", sprite data: " + totalBytes.data + ", total: " + (totalBytes.executable + totalBytes.data));
var dict = new CFMutableDictionary();
dict.setValueForKey("executable", totalBytes.executable);
dict.setValueForKey("data", totalBytes.data);
dict.setValueForKey("mhtml", totalBytes.mhtml);
plist.setValueForKey("CPApplicationSize", dict);
fs.writeFileSync(path.join(buildDir, configuration, productName, "Info.plist"), CFPropertyList.stringFromPropertyList(plist, format), { encoding: "utf8" });
}
function addBundleFileSizes(bundlePath, totalBytes)
{
var bundleName = path.basename(bundlePath),
environment = bundleName === "Foundation" ? "Objj" : "Browser",
bundlePath = path.join(bundlePath, environment + ".environment");
if (fs.existsSync(bundlePath) && fs.lstatSync(bundlePath).isDirectory())
{
var filename = bundleName + ".sj",
filePath = path.join(bundlePath, filename);
if (fs.existsSync(filePath)) {
totalBytes.executable += fs.lstatSync(filePath).size;
}
filePath = path.join(bundlePath, "dataURLs.txt");
if (fs.existsSync(filePath))
totalBytes.data += fs.lstatSync(filePath).size;
filePath = path.join(bundlePath, "MHTMLData.txt");
if (fs.existsSync(filePath))
totalBytes.mhtml += fs.lstatSync(filePath).size;
filePath = path.join(bundlePath, "MHTMLPaths.txt");
if (fs.existsSync(filePath))
totalBytes.mhtml += fs.lstatSync(filePath).size;
}
}
''')
def migrate_file(jakefile_path, apply_changes):
text = jakefile_path.read_text()
project_name = jakefile_path.parent.name
header_match = HEADER_RE.match(text)
header = header_match.group(0).rstrip("\n") if header_match else ""
fields = {"project_name": project_name}
for name, pattern in FIELD_PATTERNS.items():
m = re.search(pattern, text)
fields[name] = m.group(1) if m else DEFAULTS[name]
body = BODY_TEMPLATE.substitute(fields)
new_content = (header + "\n\n" if header else "") + body
if apply_changes:
backup_path = jakefile_path.with_name("JakefileBackup")
if not backup_path.exists():
shutil.copy2(jakefile_path, backup_path)
jakefile_path.write_text(new_content)
def find_missing_jakefile_dirs(root, jakefile_dirs):
"""Directories that look like app roots (contain Info.plist or
index.html) but have no Jakefile of their own."""
candidates = set()
for marker in ("Info.plist", "index.html"):
for p in root.rglob(marker):
if any(part in ("Frameworks", ".Frameworks") for part in p.parts):
continue
candidates.add(p.parent)
return sorted(candidates - jakefile_dirs)
def main():
parser = argparse.ArgumentParser(
description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
)
parser.add_argument("--apply", action="store_true", help="write changes (default is dry run)")
args = parser.parse_args()
root = Path(".")
manual_jakefile = (root / "Jakefile").resolve()
jakefiles = sorted(
p for p in root.rglob("Jakefile")
if not any(part in ("Frameworks", ".Frameworks") for part in p.parts)
and p.resolve() != manual_jakefile
)
jakefile_dirs = {jf.parent for jf in jakefiles}
missing_dirs = find_missing_jakefile_dirs(root, jakefile_dirs)
if not jakefiles and not missing_dirs:
sys.exit(f"no Jakefiles or app directories found under {root}")
migrated_count = 0
for jf in jakefiles:
migrate_file(jf, args.apply)
migrated_count += 1
for d in missing_dirs:
print(f"[ no Jakefile] {d}: skipped -- no Jakefile present")
verb = "migrated" if args.apply else "would migrate"
print()
print(f"Summary: {migrated_count} {verb}, {len(missing_dirs)} no Jakefile")
if not args.apply:
print("\nDry run only -- re-run with --apply to write changes.")
if __name__ == "__main__":
main()