docs(examples): add library-with-tests example exercising cabin test (#1353)

Author: ken-matsui

crates/cabin/tests/cabin_examples.rs

@@ -273,3 +273,34 @@ fn zlib_usage_builds_and_runs() {
         "zlib-usage run: stdout = {stdout}"
     );
 }
+
+#[test]
+fn library_with_tests_runs_tests() {
+    if !build_tools_available() {
+        eprintln!("test skipped: requires ninja + a C++ compiler");
+        return;
+    }
+    let dir = copy_example("library-with-tests");
+    // `cabin test` builds every `type = "test"` target and runs each,
+    // so this single command exercises the whole example.
+    let output = cabin()
+        .args(["test", "--manifest-path"])
+        .arg(dir.path().join("cabin.toml"))
+        .arg("--build-dir")
+        .arg(dir.path().join("build"))
+        .assert()
+        .success()
+        .get_output()
+        .clone();
+    let stdout = String::from_utf8(output.stdout).expect("stdout is utf-8");
+    for expected in [
+        "test library-with-tests:calc_test ... ok",
+        "test library-with-tests:parity_test ... ok",
+        "test result: ok. 2 passed; 0 failed (of 2)",
+    ] {
+        assert!(
+            stdout.contains(expected),
+            "library-with-tests test: missing `{expected}`; stdout = {stdout}"
+        );
+    }
+}

examples/README.md

@@ -23,6 +23,7 @@ Each example has its own `cabin.toml`, sources, and `README.md`.
 | [`hello-c/`](hello-c) | Smallest useful C project: one `executable` target with a `.c` source. |
 | [`hello-cpp/`](hello-cpp) | Smallest useful C++ project: one `executable` target with a `.cc` source. |
 | [`library-and-app/`](library-and-app) | A library target consumed by an executable target in the same package, with `include_dirs` propagation. |
+| [`library-with-tests/`](library-with-tests) | A library plus two `test` targets, run with `cabin test`. The example to read for unit testing. |
 | [`workspace-basic/`](workspace-basic) | A virtual workspace root with two members (`util` library, `cli` executable depending on `util` via a path dependency). |
 | [`zlib-usage/`](zlib-usage) | Consuming the curated zlib foundation port from [`crates/cabin-port/ports/zlib/`](../crates/cabin-port/ports/zlib). |
 

examples/library-with-tests/README.md

@@ -0,0 +1,44 @@
+# library-with-tests
+
+A single Cabin package with a `library` target and two `test` targets
+that exercise it. This is the example to read for `cabin test`.
+
+A Cabin `test` target is an ordinary executable: it **passes when its
+`main()` returns `0`** and fails otherwise. There is no framework,
+macro, or attribute to learn. `cabin test` builds every `type = "test"`
+target, runs each one, and reports a per-target `... ok` / `... FAILED`
+line plus a summary. Tests run in a deterministic order — by package
+name, then target name — so `calc_test` always runs before
+`parity_test`.
+
+Both tests depend on the `calc` library through `deps = ["calc"]` and
+include its public header through `calc`'s `include_dirs = ["include"]`.
+
+## Run the tests
+
+```sh
+cd examples/library-with-tests
+cabin test
+```
+
+Expected output (the `Compiling …` build line goes to stderr and is
+omitted here):
+
+```
+running 2 tests
+running test library-with-tests:calc_test
+running test library-with-tests:parity_test
+test library-with-tests:calc_test ... ok
+test library-with-tests:parity_test ... ok
+test result: ok. 2 passed; 0 failed (of 2)
+```
+
+A passing test is silent on stdout. The `check(...)` helper in
+`tests/*.cc` only writes (to stderr) when an assertion fails, which
+also makes that target exit non-zero so `cabin test` reports it as
+`FAILED (exit N)` and the command exits non-zero.
+
+This package has no `executable` target, so `cabin run` does not apply
+here. A plain `cabin build` compiles only the `calc` library; the
+`test` targets are dev-only, so `cabin test` is what builds *and* runs
+the two test binaries.

examples/library-with-tests/cabin.toml

@@ -0,0 +1,18 @@
+[package]
+name = "library-with-tests"
+version = "0.1.0"
+
+[target.calc]
+type = "library"
+sources = ["src/calc.cc"]
+include_dirs = ["include"]
+
+[target.calc_test]
+type = "test"
+sources = ["tests/calc_test.cc"]
+deps = ["calc"]
+
+[target.parity_test]
+type = "test"
+sources = ["tests/parity_test.cc"]
+deps = ["calc"]

examples/library-with-tests/include/calc/calc.hpp

@@ -0,0 +1,14 @@
+#pragma once
+
+namespace calc {
+
+// Sum of two integers.
+int add(int a, int b);
+
+// Product of the integers 1..=n for n >= 0. factorial(0) == 1.
+long factorial(int n);
+
+// True when n is divisible by two.
+bool is_even(int n);
+
+}  // namespace calc

examples/library-with-tests/src/calc.cc

@@ -0,0 +1,21 @@
+#include "calc/calc.hpp"
+
+namespace calc {
+
+int add(int a, int b) {
+    return a + b;
+}
+
+long factorial(int n) {
+    long result = 1;
+    for (int i = 2; i <= n; ++i) {
+        result *= i;
+    }
+    return result;
+}
+
+bool is_even(int n) {
+    return n % 2 == 0;
+}
+
+}  // namespace calc

examples/library-with-tests/tests/calc_test.cc

@@ -0,0 +1,28 @@
+#include "calc/calc.hpp"
+
+#include <cstdio>
+
+// A Cabin `test` target is just an executable: it passes when `main`
+// returns 0 and fails otherwise. There is no framework to learn. This
+// tiny helper records failures and stays silent on success, so a
+// passing run produces no stray output.
+namespace {
+
+int failures = 0;
+
+void check(bool condition, const char* what) {
+    if (!condition) {
+        std::fprintf(stderr, "FAILED check: %s\n", what);
+        ++failures;
+    }
+}
+
+}  // namespace
+
+int main() {
+    check(calc::add(2, 3) == 5, "add(2, 3) == 5");
+    check(calc::add(-4, 4) == 0, "add(-4, 4) == 0");
+    check(calc::factorial(0) == 1, "factorial(0) == 1");
+    check(calc::factorial(5) == 120, "factorial(5) == 120");
+    return failures;
+}

examples/library-with-tests/tests/parity_test.cc

@@ -0,0 +1,26 @@
+#include "calc/calc.hpp"
+
+#include <cstdio>
+
+// Second test target for the same library. `cabin test` discovers and
+// runs both, in a deterministic order (by package, then target name),
+// so this one always runs after `calc_test`.
+namespace {
+
+int failures = 0;
+
+void check(bool condition, const char* what) {
+    if (!condition) {
+        std::fprintf(stderr, "FAILED check: %s\n", what);
+        ++failures;
+    }
+}
+
+}  // namespace
+
+int main() {
+    check(calc::is_even(0), "is_even(0)");
+    check(calc::is_even(4), "is_even(4)");
+    check(!calc::is_even(7), "!is_even(7)");
+    return failures;
+}