test: the skeleton's tests in mtest 0.3.0's form; --case reaches the cases a listed case declares

Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>

Author: Sunrisepeak

CHANGELOG.md

@@ -14,13 +14,16 @@
   variables and reports its cases: the record names the protocol and each
   case's result and failures, a case a crash left open failed, and a failing
   program's report names its failed cases with their places. `--case PATTERN`
-  runs the matching cases, `--cases` lists them, `--seed N` states the seed. A
+  runs the matching cases -- a name below a listed case selects the case that
+  case declares, which is reported when it runs (P3.4), and a pattern below it
+  runs the listed case whole --, `--cases` lists them, `--seed N` states the seed. A
   program that implements no protocol is one case and receives none of the
   variables. `--no-run` records each built test with its program and the files
   it is compiled from; `--print-launch` states the protocol; the feature
   `test-protocol` names all of it (e2e 1035).
-- `mcpp new` scaffolds tests with mtest: the skeleton's test is a file of
-  mtest's cases with no `main`, with the dev-dependency `mcpplibs.mtest`, and
+- `mcpp new` scaffolds tests with mtest 0.3.0: the skeleton's test is a file of
+  mtest's cases with no `main` (`UTest smoke{"...", [] { ... }}`: an object is a
+  case, its type its kind), with the dev-dependency `mcpplibs.mtest`, and
   `--template lib` scaffolds a library -- a module, a partition it exports and
   the partition's implementation, named after the package -- with its test
   (docs/01; e2e 1037).

docs/01-getting-started.md

@@ -102,15 +102,15 @@ int main() {
 ```
 
 The test is a file of [mtest](https://github.com/mcpp-community/mtest)'s cases
-with no `main`, and the manifest names it a dev-dependency:
+with no `main`, and the manifest names it a dev-dependency. Each object is one
+case; its type is its kind (`UTest`, `E2E`, `CTS`, `Bench`), and the attributes
+after its name state how it runs (resources, time limit, isolation, retries):
 
 ```cpp
 import mcpplibs.mtest;
 using namespace mcpplibs::mtest;
 
-suite smoke{"smoke", [] {
-    "the project builds and its test runs"_test = [] { expect(eq(1 + 1, 2)); };
-}};
+UTest smoke{"the project builds and its test runs", [] { expect(eq(1 + 1, 2)); }};
 ```
 
 ### Creating a library

docs/08-testing.md

@@ -327,9 +327,12 @@ mcpp test --seed 42             # the seed of anything random in the cases
 - A failing program's report names each failed case with the place of its
   first failure: `case fs/read failed at tests/fs.cpp:12: ...`.
 - A pattern of `--case` matches with `*` and `?`; a name without either
-  matches itself and the cases below it (`fs` matches `fs/read`). Under
-  `--case`, a program with no matching case, and every program that implements
-  no protocol, does not run.
+  matches itself and the cases below it (`fs` matches `fs/read`). A case that
+  a listed case declares is reported when it runs and need not be listed
+  (protocol P3.4; mtest's `UTest fs{"fs", [] { "read"_test = ...; }}` lists
+  `fs`): a name below a listed case selects that one case, and a pattern below
+  it runs the listed case whole. Under `--case`, a program with no matching
+  case, and every program that implements no protocol, does not run.
 - A program that implements no protocol is one case, judged by its exit status,
   and receives none of the variables, even when mcpp's own environment has
   them.

docs/zh/01-getting-started.md

@@ -100,15 +100,14 @@ int main() {
 ```
 
 测试是一个不定义 `main` 的 [mtest](https://github.com/mcpp-community/mtest) 用例文件，manifest 把 mtest
-列为 dev-dependency：
+列为 dev-dependency。每个对象是一个用例：类型即类别（`UTest`、`E2E`、`CTS`、`Bench`），名字之后的属性说明它如何
+运行（资源、时限、隔离、重试）：
 
 ```cpp
 import mcpplibs.mtest;
 using namespace mcpplibs::mtest;
 
-suite smoke{"smoke", [] {
-    "the project builds and its test runs"_test = [] { expect(eq(1 + 1, 2)); };
-}};
+UTest smoke{"the project builds and its test runs", [] { expect(eq(1 + 1, 2)); }};
 ```
 
 ### 创建库

docs/zh/08-testing.md

@@ -276,6 +276,8 @@ mcpp test --seed 42             # 用例中随机性的种子
   原因是程序的退出码。
 - 失败程序的报告列出每个失败的用例及其第一处失败的位置：`case fs/read failed at tests/fs.cpp:12: ...`。
 - `--case` 的模式以 `*` 与 `?` 匹配；不含二者的名字匹配它自身及其下的用例（`fs` 匹配 `fs/read`）。
+  已列举的用例所声明的用例在运行时报告，可以不被列举（协议 P3.4；mtest 的 `UTest fs{"fs", [] { "read"_test = ...; }}`
+  只列举 `fs`）：已列举用例之下的名字选中该用例，之下的模式则完整运行该已列举用例。
   使用 `--case` 时，没有匹配用例的程序与所有未实现协议的程序不运行。
 - 未实现协议的程序是一个用例，以退出码判定，并且收不到任何协议变量，即使 mcpp 自身的环境中有它们。
 

src/build/execute.cppm

@@ -5162,11 +5162,8 @@ static int test_run_member(TestBuild& tb, const TestOptions& testOpts,
                 continue;
             }
             std::string lines;
-            for (const auto& c : report.listed)
-                if (std::ranges::any_of(testOpts.cases, [&](const std::string& p) {
-                        return mcpp::build::test_protocol::matches(c.id, p);
-                    }))
-                    lines += c.id + "\n";
+            for (const auto& id : mcpp::build::test_protocol::selection(report.listed, testOpts.cases))
+                lines += id + "\n";
             if (lines.empty()) { ++notSelected; continue; }
             r.select = r.protocolDir / "select.txt";
             std::ofstream(*r.select, std::ios::binary) << lines;

src/build/test_protocol.cppm

@@ -18,7 +18,7 @@ inline constexpr int kVersion = 1;
 
 // The framework mcpp scaffolds tests with and suggests where a package has
 // none (docs/01, docs/08): mtest, by this release, from its repository.
-inline constexpr std::string_view kMtestRelease = "0.2.0";
+inline constexpr std::string_view kMtestRelease = "0.3.0";
 inline constexpr std::string_view kMtestRepo    = "https://github.com/mcpp-community/mtest";
 
 // The protocol's variables, removed from the environment a program inherits
@@ -98,6 +98,14 @@ variables(std::string_view mode, const std::filesystem::path& report,
 // it equals or the identifiers it is a `/`-prefix of (`fs` matches `fs/read`).
 bool matches(std::string_view id, std::string_view pattern);
 
+// The identifiers `mcpp test --case` passes a program (P4.1), from its listing:
+// each listed case a pattern matches; for a pattern under a listed case -- a
+// case that case declares, which the program reports when it runs and need not
+// list (P3.4) -- the pattern itself when it names one case, else the listed
+// case, all of whose cases then run.
+std::vector<std::string> selection(const std::vector<Case>& listed,
+                                   const std::vector<std::string>& patterns);
+
 // The JSON of a report in a `mcpp test --message-format json` record
 // (docs/50): `cases` and `missing`.
 nlohmann::json cases_json(const Report& r);
@@ -278,6 +286,26 @@ bool matches(std::string_view id, std::string_view pattern) {
                              && id[pattern.size()] == '/');
 }
 
+std::vector<std::string> selection(const std::vector<Case>& listed,
+                                   const std::vector<std::string>& patterns) {
+    std::vector<std::string> out;
+    auto add = [&](const std::string& id) {
+        if (std::ranges::find(out, id) == out.end()) out.push_back(id);
+    };
+    for (const auto& p : patterns) {
+        bool found = false;
+        for (const auto& c : listed)
+            if (matches(c.id, p)) { add(c.id); found = true; }
+        if (found) continue;
+        const auto under = std::ranges::find_if(listed, [&](const Case& c) {
+            return p.size() > c.id.size() && p.starts_with(c.id) && p[c.id.size()] == '/';
+        });
+        if (under == listed.end()) continue;
+        add(p.find_first_of("*?") == std::string::npos ? p : under->id);
+    }
+    return out;
+}
+
 nlohmann::json cases_json(const Report& r) {
     nlohmann::json cases = nlohmann::json::array();
     for (const auto& c : r.cases) {

src/scaffold/create.cppm

@@ -488,28 +488,24 @@ std::string hello(std::string_view name) {
                 "cannot create scaffold test directory: {}", ec.message()));
             return 1;
         }
-        constexpr std::string_view smoke = R"(// A test of {{project.name}}: each `_test` is a case `mcpp test` lists, selects and reports.
-// More tests are more files under tests/; a file defines no `main`.
+        constexpr std::string_view smoke = R"(// A test of {{project.name}}: each object is a case `mcpp test` lists, selects and reports.
+// More tests are more objects, or more files under tests/; a file defines no `main`.
 import mcpplibs.mtest;
 
 using namespace mcpplibs::mtest;
 
-suite smoke{"smoke", [] {
-    "the project builds and its test runs"_test = [] { expect(eq(1 + 1, 2)); };
-}};
+UTest smoke{"the project builds and its test runs", [] { expect(eq(1 + 1, 2)); }};
 )";
-        constexpr std::string_view greeting = R"(// The cases of {{project.module}}: each `_test` is one `mcpp test` lists, selects and reports.
-// More tests are more files under tests/; a file defines no `main`.
+        constexpr std::string_view greeting = R"(// The cases of {{project.module}}: each object is one `mcpp test` lists, selects and reports.
+// More tests are more objects, or more files under tests/; a file defines no `main`.
 import std;
 import mcpplibs.mtest;
 import {{project.module}};
 
 using namespace mcpplibs::mtest;
 
-suite greeting{"hello", [] {
-    "greets by name"_test = [] {
-        expect(eq({{project.cxxNamespace}}::hello("mcpp"), std::string("Hello, mcpp!")));
-    };
+UTest greeting{"hello greets by name", [] {
+    expect(eq({{project.cxxNamespace}}::hello("mcpp"), std::string("Hello, mcpp!")));
 }};
 )";
         mcpp::scaffold::RenderVars vars{

tests/e2e/1038_test_programs_of_a_directory_and_the_tests_a_change_affects.sh

@@ -17,6 +17,8 @@
 #   E. Under a shipping profile, `mcpp build` and `mcpp test` are one configuration: the test
 #      compiles none of the code under test again, which is trimmed as the build trims it, and a
 #      test program's own file keeps its path (`__FILE__` finds the test's directory).
+#   F. A case a listed case declares (protocol P3.4) is selected by its name alone; a pattern below
+#      the listed case runs it whole.
 set -e
 TMP=$(mktemp -d)
 trap 'rm -rf "$TMP"' EXIT
@@ -34,13 +36,13 @@ cat > tests/unit/a.cpp <<'CPP'
 import mcpplibs.mtest;
 import app.calc;
 using namespace mcpplibs::mtest;
-suite a{"a", [] { "doubles"_test = [] { expect(eq(twice(2), 4)); }; }};
+UTest a{"doubles", [] { expect(eq(twice(2), 4)); }};
 CPP
 cat > tests/unit/b.cpp <<'CPP'
 import std;
 import mcpplibs.mtest;
 using namespace mcpplibs::mtest;
-suite b{"b", [] { "reads its data"_test = [] { expect(eq(std::string_view("tests/data/f.txt").size(), 16u)); }; }};
+UTest b{"reads its data", [] { expect(eq(std::string_view("tests/data/f.txt").size(), 16u)); }};
 CPP
 printf 'import std;\nint main() { return 0; }\n' > tests/e2e/plain.cpp
 printf 'data\n' > tests/data/f.txt
@@ -51,7 +53,7 @@ printf '\n[test]\nprograms = "directory"\n' >> mcpp.toml
 grep -q 'unit \.\.\. ok (.*2 cases)' a.log || fail "A: unit is not one program of two cases" a.log
 grep -q '^e2e \.\.\. ok' a.log || fail "A: the directory of a file with main" a.log
 "$MCPP" test --cases > a-cases.log 2>&1 || fail "A: --cases" a-cases.log
-grep -q 'a/doubles' a-cases.log && grep -q 'b/reads its data' a-cases.log || fail "A: the program's cases" a-cases.log
+grep -q 'doubles' a-cases.log && grep -q 'reads its data' a-cases.log || fail "A: the program's cases" a-cases.log
 # B: a file of plain main beside the library's marker.
 grep -q 'e2e: one case, its exit status' a-cases.log || fail "B: a program of plain main is listed as one case" a-cases.log
 printf 'int main() { return 0; }\n' > tests/e2e/second.cpp
@@ -113,4 +115,23 @@ set -- target/*/*/build.ninja
 grep -q "library rel@0.1.0/src/where.cppm" e-test.log || fail "E: the code under test is not trimmed as built" e-test.log
 [ "$(grep -cE 'obj/where\.m\.(o|obj)	' "$(dirname "$1")/.ninja_log")" = 1 ] || fail "E: the test compiled the library again" "$(dirname "$1")/.ninja_log"
 
+# F
+cd "$TMP"
+"$MCPP" new grp > /dev/null 2>&1
+cd grp
+cat > tests/test_smoke.cpp <<'CPP'
+import mcpplibs.mtest;
+using namespace mcpplibs::mtest;
+UTest g{"g", [] {
+    "one"_test = [] { expect(true); };
+    "two"_test = [] { expect(true); };
+}};
+CPP
+"$MCPP" test --cases > f-cases.log 2>&1 || fail "F: --cases" f-cases.log
+grep -q 'test_smoke: 1 case' f-cases.log || fail "F: the object is the one listed case" f-cases.log
+"$MCPP" test --case 'g/one' > f1.log 2>&1 || fail "F: --case g/one" f1.log
+grep -q 'test_smoke \.\.\. ok (.*1 case)' f1.log || fail "F: a declared case is not selected alone" f1.log
+"$MCPP" test --case 'g/t*' > f2.log 2>&1 || fail "F: --case g/t*" f2.log
+grep -q 'test_smoke \.\.\. ok (.*3 cases)' f2.log || fail "F: a pattern below the listed case does not run it whole" f2.log
+
 echo "PASS: 1038 test programs of a directory, and the tests a change affects"

tests/unit/test_test_protocol.cpp

@@ -87,6 +87,17 @@ TEST(TestProtocol, APatternMatchesIdentifiers) {
         EXPECT_EQ(tp::matches(row.id, row.pattern), row.matches) << row.id << " ~ " << row.pattern;
 }
 
+TEST(TestProtocol, ASelectionReachesTheCasesAListedCaseDeclares) {
+    // P3.4: `fields` is listed; the cases its body declares are reported when it runs.
+    const std::vector<tp::Case> listed = {{"fields"}, {"empty"}};
+    using V = std::vector<std::string>;
+    EXPECT_EQ(tp::selection(listed, {"fields"}), V{"fields"});
+    EXPECT_EQ(tp::selection(listed, {"fields/one"}), V{"fields/one"});      // passed as it is
+    EXPECT_EQ(tp::selection(listed, {"fields/o*"}), V{"fields"});           // the listed case, all of it
+    EXPECT_EQ(tp::selection(listed, {"e*", "fields/one", "fields"}), (V{"empty", "fields/one", "fields"}));
+    EXPECT_EQ(tp::selection(listed, {"other/one"}), V{});
+}
+
 TEST(TestProtocol, TheVariablesOfARun) {
     auto env = tp::variables("run", "/r", std::filesystem::path("/s"), "/t", 7);
     std::map<std::string, std::string> m(env.begin(), env.end());