feature: Test tags (TestTag) for UniTest — run testing layers separately

[xerial]

Why

Part of making Uni a foundation for multi-layer testing of rich desktop apps (see plans/2026-06-27-multi-layer-testing.md). VSCode keeps separate test commands per layer (unit / integration / UI / smoke); to do the same here, UniTest needs a way to mark which layer a test belongs to and run/skip one layer at a time. This is the mechanism that makes the other layers (UI toolkit, Electron harness in #616) runnable as independent suites in CI.

What

A TestTag varargs API on test(...) that unifies the old flaky boolean and ad-hoc tags:

test("renders the toolbar", UI) { ... }
test("hits the network", Electron, Slow) { ... }
test("retried under load", Flaky) { ... }      // Flaky is itself a tag: failure -> skipped
test("smoke check", TestTag("smoke")) { ... }  // custom tag (or a bare string)

• trait TestTag { def name: String }; built-ins Flaky, UI, Electron, Integration, Slow exported into UniTest scope; custom via TestTag("name") or a String (given Conversion).
• test(name: String, tags: TestTag*)(body) — isFlaky derives from the presence of Flaky; TestDef stays string-based internally so the runner is unchanged.
• sbt selection (long options use a -- prefix per repo convention; short options -l/-t: keep one hyphen):
  • --tags:a,b — include filter: run only tests carrying any of these tags
  • --exclude-tags:a,b — exclude filter: skip tests carrying any of these tags
  • exclusion wins over inclusion
• Documented in .github/instructions/unitest.instructions.md.

./sbt "coreJVM/testOnly * -- --tags:ui,electron"    # ui OR electron
./sbt "coreJVM/testOnly * -- --exclude-tags:slow"   # everything except slow

Breaking change

test(name, flaky = true) → test(name, Flaky); test(name, tags = Seq("ui")) → test(name, UI) (or TestTag("ui")). Only one in-repo call site used flaky = true; it's migrated. No other open branch uses the old params.

Tests

TagFilterTest (12) covers arg parsing, includesTags semantics, TestTag names, the Flaky→isFlaky mapping, layer-tag registration, and the String conversion. Verified end-to-end via the sbt runner (--tags:meta → 1 test, --exclude-tags:meta → rest). Full uni-test JVM suite green (69); JS + Native and every JVM test module compile.

Roadmap: unit → UI (#616) → Electron (#616) → tags (this) → plugin (#618).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces test tagging and filtering capabilities to the uni-test framework, allowing users to run or skip specific testing layers (such as unit, UI, or integration tests) using the -tag: and -xtag: command-line options. The changes include updates to the configuration parser, task runner, documentation, and a new suite of unit tests. The feedback suggests trimming and filtering empty strings from the tags during registration to prevent potential issues with leading or trailing whitespace.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To prevent subtle bugs where tests are silently skipped due to accidental leading/trailing whitespace or empty strings in the tags parameter (e.g., Seq(" ui ")), it is safer to trim and filter the tags when registering them, just like we do when parsing command-line arguments.

  protected def test(name: String, flaky: Boolean = false, tags: Seq[String] = Nil)(
      body: => Any
  ): Unit = _tests += TestDef(name, () => body, _context, isFlaky = flaky, tags = tags.map(_.trim).filter(_.nonEmpty).toSet)