Add test suite for wire format, schema, and codegen (#14)

Adds a zero-dependency test suite covering the parts of the toolchain
that previously had no automated coverage: the binary wire format,
schema parsing, and code generation. Runs in CI between building the
toolchain and the examples.

Author: io-eric

.github/workflows/ci.yml

@@ -21,6 +21,9 @@ jobs:
     - name: Build Toolchain
       run: ./build.sh
 
+    - name: Run Tests
+      run: ./tests/run.sh
+
     - name: Build Examples
       run: |
         EXAMPLES=(

tests/.gitignore

@@ -0,0 +1 @@
+build/

tests/README.md

@@ -0,0 +1,45 @@
+# WebCC Tests
+
+Zero-dependency test suite covering the binary wire format, schema parsing, and
+code generation.
+
+```sh
+./tests/run.sh            # build & run everything
+./tests/run.sh --update   # regenerate golden snapshots, then run
+./tests/run.sh --skip-js  # C++ tests only (no webcc build / node needed)
+```
+
+Exit code is non-zero on any failure, so CI fails loudly. The suite runs in CI
+(`.github/workflows/ci.yml`) between building the toolchain and the examples.
+
+## Layers
+
+**C++ unit tests** (host-native, linked against the real toolchain sources):
+
+| File | What it covers |
+| --- | --- |
+| [test_command_buffer.cc](test_command_buffer.cc) | The C++/JS wire format: little-endian ints, IEEE-754 floats/doubles, 8-byte double alignment, 4-byte string padding. This is the contract the generated JS decoder walks. |
+| [test_schema.cc](test_schema.cc) | `load_defs` parsing: opcode assignment, `handle(T)` extraction, `RET:` handling, inheritance, pipes inside JS actions, plus the `schema.wcc.bin` binary-cache round-trip. |
+| [test_codegen.cc](test_codegen.cc) | Golden snapshots of `emit_headers` and `generate_js_runtime` output, plus tree-shaking assertions (a canvas-only build embeds canvas code and not DOM/WebSocket/WebGPU). |
+
+**JS validation** ([js/check_js.mjs](js/check_js.mjs)): generates `app.js` for
+several feature combinations using the real `webcc` binary and parses each with
+Node's `vm.Script`, confirming the generated JavaScript is syntactically valid.
+
+## Snapshots
+
+Golden files live in [snapshots/](snapshots/). When you change codegen, run
+`./tests/run.sh --update` and review the diff before committing. The diff is the
+review of your generator change.
+
+## Adding a test
+
+Add a `TEST(name) { ... }` block (see [framework.h](framework.h)) to any
+`test_*.cc`, then list the file in the compile line in [run.sh](run.sh). Tests
+self-register; no manual wiring.
+
+## Possible next addition
+
+The JS layer syntax-checks `app.js`. A full execution round-trip (C++ encodes
+commands, the generated JS decoder runs, assert the decoded DOM/canvas calls)
+would extend coverage to the runtime behavior end to end.

tests/framework.h

@@ -0,0 +1,141 @@
+// Tiny zero-dependency test framework for WebCC.
+//
+// Usage:
+//   TEST(my_test_name) {
+//       CHECK(some_condition);
+//       CHECK_EQ(actual, expected);
+//   }
+//
+// Tests self-register at static-init time. The `tests` binary (test_main.cc)
+// calls webcc_test::run_all() to execute them all and returns non-zero on any
+// failure. No macros leak a main(); link as many test_*.cc files as you like.
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <iostream>
+#include <sstream>
+#include <string>
+#include <vector>
+
+namespace webcc_test
+{
+    struct TestCase
+    {
+        std::string name;
+        std::function<void()> fn;
+    };
+
+    // Per-run state. Failures are appended here by the CHECK macros.
+    struct Context
+    {
+        std::vector<std::string> failures;
+        std::string current_test;
+    };
+
+    inline std::vector<TestCase> &registry()
+    {
+        static std::vector<TestCase> r;
+        return r;
+    }
+
+    inline Context &ctx()
+    {
+        static Context c;
+        return c;
+    }
+
+    inline int register_test(const std::string &name, std::function<void()> fn)
+    {
+        registry().push_back({name, std::move(fn)});
+        return 0;
+    }
+
+    inline void record_failure(const std::string &msg)
+    {
+        ctx().failures.push_back(ctx().current_test + ": " + msg);
+    }
+
+    inline int run_all()
+    {
+        int passed = 0;
+        int failed = 0;
+        for (auto &tc : registry())
+        {
+            ctx().current_test = tc.name;
+            size_t before = ctx().failures.size();
+            try
+            {
+                tc.fn();
+            }
+            catch (const std::exception &e)
+            {
+                record_failure(std::string("threw exception: ") + e.what());
+            }
+            catch (...)
+            {
+                record_failure("threw unknown exception");
+            }
+            bool ok = ctx().failures.size() == before;
+            std::cout << (ok ? "  PASS  " : "  FAIL  ") << tc.name << "\n";
+            ok ? ++passed : ++failed;
+        }
+
+        std::cout << "\n";
+        if (failed)
+        {
+            std::cout << "Failures:\n";
+            for (const auto &f : ctx().failures)
+                std::cout << "  - " << f << "\n";
+            std::cout << "\n";
+        }
+        std::cout << passed << " passed, " << failed << " failed, "
+                  << registry().size() << " total.\n";
+        return failed == 0 ? 0 : 1;
+    }
+
+    // Stringify helper used by CHECK_EQ.
+    template <typename T>
+    std::string to_str(const T &v)
+    {
+        std::ostringstream ss;
+        ss << v;
+        return ss.str();
+    }
+} // namespace webcc_test
+
+#define WEBCC_CAT_(a, b) a##b
+#define WEBCC_CAT(a, b) WEBCC_CAT_(a, b)
+
+#define TEST(name)                                                                \
+    static void name();                                                           \
+    static int WEBCC_CAT(name, _reg) =                                            \
+        ::webcc_test::register_test(#name, name);                                 \
+    static void name()
+
+#define CHECK(cond)                                                               \
+    do                                                                            \
+    {                                                                             \
+        if (!(cond))                                                              \
+        {                                                                         \
+            ::webcc_test::record_failure(                                         \
+                std::string("CHECK failed: " #cond " (") + __FILE__ + ":" +       \
+                std::to_string(__LINE__) + ")");                                  \
+        }                                                                         \
+    } while (0)
+
+#define CHECK_EQ(actual, expected)                                                \
+    do                                                                            \
+    {                                                                             \
+        auto _a = (actual);                                                       \
+        auto _e = (expected);                                                     \
+        if (!(_a == _e))                                                          \
+        {                                                                         \
+            ::webcc_test::record_failure(                                         \
+                std::string("CHECK_EQ failed: " #actual " == " #expected          \
+                            " (got '") +                                          \
+                ::webcc_test::to_str(_a) + "', expected '" +                      \
+                ::webcc_test::to_str(_e) + "') (" + __FILE__ + ":" +              \
+                std::to_string(__LINE__) + ")");                                  \
+        }                                                                         \
+    } while (0)

tests/js/check_js.mjs

@@ -0,0 +1,106 @@
+// Validates that generated app.js is syntactically valid JavaScript.
+//
+// app.js is assembled from string templates and schema-derived action snippets
+// in generators.cc. This uses the webcc binary to generate app.js for a range of
+// feature combinations and syntax-checks each with `new vm.Script`, so a
+// malformed JS action is caught in CI rather than at runtime in the browser.
+//
+// Usage: node tests/js/check_js.mjs <path-to-webcc-binary> <repo-root>
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import vm from "node:vm";
+
+const [, , webccBin, repoRoot] = process.argv;
+if (!webccBin || !repoRoot) {
+  console.error("usage: node check_js.mjs <webcc-binary> <repo-root>");
+  process.exit(2);
+}
+
+// Feature programs chosen to exercise different generator paths:
+// void commands, return-value imports, event delegation, string args, floats.
+const cases = {
+  canvas: `#include "webcc/canvas.h"
+int main(){ auto c=webcc::canvas::create_canvas("c",640,480);
+  auto x=webcc::canvas::get_context_2d(c);
+  webcc::canvas::fill_rect(x,0,0,100,100);
+  webcc::canvas::fill_text(x,"hi",10,10); }`,
+
+  dom_events: `#include "webcc/dom.h"
+int main(){ auto b=webcc::dom::get_body();
+  auto i=webcc::dom::create_element("input");
+  webcc::dom::add_input_listener(i);
+  webcc::dom::add_click_listener(i);
+  webcc::dom::append_child(b,i); }`,
+
+  webgl: `#include "webcc/webgl.h"
+#include "webcc/canvas.h"
+int main(){ auto c=webcc::canvas::create_canvas("c",640,480);
+  auto gl=webcc::canvas::get_context_webgl(c);
+  webcc::webgl::clear_color(gl,0,0,0,1);
+  webcc::webgl::clear(gl,16384); }`,
+
+  websocket: `#include "webcc/websocket.h"
+int main(){ auto ws=webcc::websocket::connect("wss://x");
+  webcc::websocket::send(ws,"hello"); }`,
+
+  fetch_storage: `#include "webcc/fetch.h"
+#include "webcc/storage.h"
+int main(){ webcc::fetch::get("/api","{}");
+  webcc::storage::set_item("k","v"); }`,
+
+  webgpu: `#include "webcc/wgpu.h"
+int main(){ webcc::wgpu::request_adapter(); }`,
+};
+
+const work = mkdtempSync(join(tmpdir(), "webcc-js-"));
+let failures = 0;
+
+for (const [name, src] of Object.entries(cases)) {
+  const srcPath = join(work, `${name}.cc`);
+  const outDir = join(work, name);
+  writeFileSync(srcPath, src);
+  execFileSync("mkdir", ["-p", outDir]);
+
+  // We only need JS generation, which happens before WASM compilation. We let
+  // webcc run fully; if the toolchain can compile it too, great, but a compile
+  // failure shouldn't mask a JS syntax check. So generate, then read app.js if
+  // present.
+  try {
+    execFileSync(webccBin, ["-o", outDir, srcPath], {
+      cwd: repoRoot,
+      stdio: "pipe",
+    });
+  } catch (e) {
+    // Compilation may fail in minimal CI (missing wasm libc bits) but app.js is
+    // written before compilation. Only treat as fatal if app.js is absent.
+  }
+
+  let js;
+  try {
+    js = readFileSync(join(outDir, "app.js"), "utf8");
+  } catch {
+    console.error(`  FAIL  ${name}: app.js was not generated`);
+    failures++;
+    continue;
+  }
+
+  try {
+    // Parse-only: constructing a Script compiles (syntax-checks) without running.
+    new vm.Script(js, { filename: `${name}/app.js` });
+    console.log(`  PASS  ${name} (app.js parses, ${js.length} bytes)`);
+  } catch (e) {
+    console.error(`  FAIL  ${name}: ${e.message}`);
+    failures++;
+  }
+}
+
+rmSync(work, { recursive: true, force: true });
+
+console.log("");
+if (failures) {
+  console.error(`${failures} JS validation failure(s).`);
+  process.exit(1);
+}
+console.log("All generated app.js files are valid JavaScript.");

tests/run.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# WebCC test runner.
+#
+#   ./tests/run.sh            Build & run all tests (C++ units + codegen snapshots + JS validation)
+#   ./tests/run.sh --update   Regenerate golden snapshots, then run
+#   ./tests/run.sh --skip-js  Skip the Node JS-validation layer (no webcc build / node needed)
+#
+# Zero extra dependencies: uses the same clang++ the toolchain requires, plus
+# node (already needed to serve examples) for the JS syntax checks.
+set -e
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BUILD="$ROOT/tests/build"
+mkdir -p "$BUILD"
+
+UPDATE=0
+SKIP_JS=0
+for arg in "$@"; do
+    case "$arg" in
+        --update) UPDATE=1 ;;
+        --skip-js) SKIP_JS=1 ;;
+        *) echo "Unknown option: $arg"; exit 2 ;;
+    esac
+done
+
+CXX="${CXX:-clang++}"
+
+echo "[tests] Compiling C++ test suite..."
+"$CXX" -std=c++20 -O1 -g \
+    -I "$ROOT/src/cli" -I "$ROOT/src/core" \
+    -DWEBCC_SCHEMA_DEF="\"$ROOT/schema.def\"" \
+    -DWEBCC_SNAPSHOT_DIR="\"$ROOT/tests/snapshots\"" \
+    "$ROOT/tests/test_main.cc" \
+    "$ROOT/tests/test_command_buffer.cc" \
+    "$ROOT/tests/test_schema.cc" \
+    "$ROOT/tests/test_codegen.cc" \
+    "$ROOT/src/cli/schema.cc" \
+    "$ROOT/src/cli/utils.cc" \
+    "$ROOT/src/cli/generators.cc" \
+    "$ROOT/src/core/command_buffer.cc" \
+    -o "$BUILD/tests"
+
+echo "[tests] Running C++ test suite..."
+if [ "$UPDATE" = "1" ]; then
+    WEBCC_UPDATE_SNAPSHOTS=1 "$BUILD/tests"
+    echo "[tests] Snapshots updated. Re-running to verify..."
+fi
+"$BUILD/tests"
+CPP_STATUS=$?
+
+if [ "$SKIP_JS" = "1" ]; then
+    echo "[tests] Skipping JS validation (--skip-js)."
+    exit $CPP_STATUS
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+    echo "[tests] node not found; skipping JS validation layer."
+    exit $CPP_STATUS
+fi
+
+# Ensure the webcc binary exists for JS generation.
+if [ ! -x "$ROOT/webcc" ]; then
+    echo "[tests] webcc binary not found; building it (ninja)..."
+    ( cd "$ROOT" && ninja )
+fi
+
+echo "[tests] Validating generated JavaScript..."
+node "$ROOT/tests/js/check_js.mjs" "$ROOT/webcc" "$ROOT"