diff --git a/core/Common/Reflection.php b/core/Common/Reflection.php
index 686f5b6e..3ca4779a 100644
--- a/core/Common/Reflection.php
+++ b/core/Common/Reflection.php
@@ -175,6 +175,37 @@ public static function fetchTraits(
         return \array_unique($traits);
     }
 
+    /**
+     * Fetch the attributes of every case of an enum.
+     *
+     * Every case is present in the result, in declaration order, so a caller can walk the enum once and
+     * fall back to a default where a case carries nothing.
+     *
+     * @template T of object
+     *
+     * @param \ReflectionEnum|class-string<\UnitEnum> $enum
+     * @param class-string<T>|null $attributeClass If provided, only attributes of this class will be returned.
+     * @param int $flags Flags to pass to {@see \ReflectionEnumUnitCase::getAttributes()}.
+     *
+     * @return ($attributeClass is null
+     *     ? array<non-empty-string, list<\ReflectionAttribute>>
+     *     : array<non-empty-string, list<\ReflectionAttribute<T>>>) Attributes keyed by case name.
+     */
+    public static function fetchEnumCaseAttributes(
+        \ReflectionEnum|string $enum,
+        ?string $attributeClass = null,
+        int $flags = 0,
+    ): array {
+        \is_string($enum) and $enum = new \ReflectionEnum($enum);
+
+        $attributes = [];
+        foreach ($enum->getCases() as $case) {
+            $attributes[$case->name] = $case->getAttributes($attributeClass, $flags);
+        }
+
+        return $attributes;
+    }
+
     /**
      * Find all methods in a class that have a specific attribute.
      *
diff --git a/core/Core/Metric/Memory.php b/core/Core/Metric/Memory.php
new file mode 100644
index 00000000..1f58cb00
--- /dev/null
+++ b/core/Core/Metric/Memory.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+use Testo\Metric\Dimension;
+use Testo\Metric\Factor;
+use Testo\Metric\Unit;
+use Testo\Metric\UnitConversion;
+
+/**
+ * An amount of memory, in bytes or one of their binary (IEC) multiples — the scale PHP's own memory
+ * figures and the tools around it use, named so a kibibyte is never mistaken for a thousand bytes.
+ *
+ * @api
+ */
+#[Dimension('memory')]
+enum Memory: string implements Unit
+{
+    use UnitConversion;
+
+    #[Factor(1)]
+    case Bytes = 'B';
+
+    #[Factor(1024)]
+    case Kibibytes = 'KiB';
+
+    #[Factor(1024 ** 2)]
+    case Mebibytes = 'MiB';
+
+    #[Factor(1024 ** 3)]
+    case Gibibytes = 'GiB';
+}
diff --git a/core/Core/Metric/Percent.php b/core/Core/Metric/Percent.php
new file mode 100644
index 00000000..6e2b16a6
--- /dev/null
+++ b/core/Core/Metric/Percent.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+use Testo\Metric\Dimension;
+use Testo\Metric\Unit;
+use Testo\Metric\UnitConversion;
+
+/**
+ * A ratio already expressed out of 100.
+ *
+ * @api
+ */
+#[Dimension('percent')]
+enum Percent: string implements Unit
+{
+    use UnitConversion;
+    case Percent = 'percent';
+}
diff --git a/core/Core/Metric/Scalar.php b/core/Core/Metric/Scalar.php
new file mode 100644
index 00000000..61587c11
--- /dev/null
+++ b/core/Core/Metric/Scalar.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+use Testo\Metric\Dimension;
+use Testo\Metric\Unit;
+use Testo\Metric\UnitConversion;
+
+/**
+ * A dimensionless quantity — a count of iterations or calls, a rank.
+ *
+ * @api
+ */
+#[Dimension('number')]
+enum Scalar: string implements Unit
+{
+    use UnitConversion;
+    case Number = 'number';
+}
diff --git a/core/Core/Metric/Time.php b/core/Core/Metric/Time.php
new file mode 100644
index 00000000..5f4c88b7
--- /dev/null
+++ b/core/Core/Metric/Time.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+use Testo\Metric\Dimension;
+use Testo\Metric\Factor;
+use Testo\Metric\Unit;
+use Testo\Metric\UnitConversion;
+
+/**
+ * A duration, in one of the units it may be measured in.
+ *
+ * @api
+ */
+#[Dimension('time')]
+enum Time: string implements Unit
+{
+    use UnitConversion;
+
+    #[Factor(1)]
+    case Nanoseconds = 'ns';
+
+    #[Factor(1_000)]
+    case Microseconds = 'us';
+
+    #[Factor(1_000_000)]
+    case Milliseconds = 'ms';
+
+    #[Factor(1_000_000_000)]
+    case Seconds = 's';
+}
diff --git a/core/Metric/Dimension.php b/core/Metric/Dimension.php
new file mode 100644
index 00000000..8d52db08
--- /dev/null
+++ b/core/Metric/Dimension.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Metric;
+
+/**
+ * Names the physical quantity a {@see Unit} enum measures.
+ *
+ * Placed on the enum itself. The name is what a reporter shows or keys on when it does not care about
+ * the particular unit — `time`, `memory` — and what an error names when two units are mixed. An enum
+ * without it is still a valid unit family: the name falls back to the enum's short class name in lower case.
+ *
+ * @api
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final readonly class Dimension
+{
+    /**
+     * @param non-empty-string $name
+     */
+    public function __construct(
+        public string $name,
+    ) {}
+}
diff --git a/core/Metric/Exception/IncompatibleUnits.php b/core/Metric/Exception/IncompatibleUnits.php
new file mode 100644
index 00000000..4024655a
--- /dev/null
+++ b/core/Metric/Exception/IncompatibleUnits.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Metric\Exception;
+
+use Testo\Metric\Unit;
+
+/**
+ * Thrown when a value is converted between units of different dimensions — time into bytes.
+ *
+ * @api
+ */
+final class IncompatibleUnits extends \InvalidArgumentException
+{
+    public static function between(Unit $from, Unit $to): self
+    {
+        return new self(\sprintf(
+            'Cannot convert between units of different dimensions: %s::%s and %s::%s.',
+            $from::class,
+            $from->name,
+            $to::class,
+            $to->name,
+        ));
+    }
+}
diff --git a/core/Metric/Exception/InvalidUnitDeclaration.php b/core/Metric/Exception/InvalidUnitDeclaration.php
new file mode 100644
index 00000000..8d9ffa10
--- /dev/null
+++ b/core/Metric/Exception/InvalidUnitDeclaration.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Metric\Exception;
+
+use Testo\Metric\Unit;
+
+/**
+ * Thrown when a {@see Unit} enum is declared in a way the metric core cannot read — a non-enum class,
+ * a class that does not implement the interface, or a non-positive factor.
+ *
+ * @api
+ */
+final class InvalidUnitDeclaration extends \LogicException
+{
+    public static function notAUnitEnum(string $class): self
+    {
+        return new self(\sprintf('`%s` must be an enum implementing `%s`.', $class, Unit::class));
+    }
+
+    /**
+     * @param class-string $class
+     * @param non-empty-string $case
+     */
+    public static function nonPositiveFactor(string $class, string $case, int|float $factor): self
+    {
+        return new self(\sprintf('Factor of `%s::%s` must be positive, got `%s`.', $class, $case, (string) $factor));
+    }
+}
diff --git a/core/Metric/Factor.php b/core/Metric/Factor.php
new file mode 100644
index 00000000..b68687f2
--- /dev/null
+++ b/core/Metric/Factor.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Metric;
+
+/**
+ * How many base units one unit of this case is worth.
+ *
+ * Placed on a {@see Unit} enum case. The base is the case with factor `1` — a case without the attribute
+ * has that factor, so a single-case family such as {@see \Testo\Core\Metric\Percent} declares nothing. Converting between
+ * two cases is a ratio of their factors, and the compact form of a value is the case whose factor is the
+ * largest one the value still exceeds.
+ *
+ * @api
+ */
+#[\Attribute(\Attribute::TARGET_CLASS_CONSTANT)]
+final readonly class Factor
+{
+    /**
+     * @param int|float $value A positive multiplier to the family's base unit.
+     */
+    public function __construct(
+        public int|float $value,
+    ) {}
+}
diff --git a/core/Metric/Metric.php b/core/Metric/Metric.php
new file mode 100644
index 00000000..3aa17172
--- /dev/null
+++ b/core/Metric/Metric.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Metric;
+
+use Testo\Metric\Exception\IncompatibleUnits;
+
+/**
+ * One number a test produced, together with the unit it was measured in.
+ *
+ * The unit travels with the value rather than baked into a name, so each reporter renders it its own way
+ * — a TeamCity number `type`, a JUnit property-name suffix — instead of parsing it back out of a key. The
+ * unit's family is a type parameter, so a `Metric<Percent>` is distinct from a `Metric<Time>` and a
+ * consumer keyed to a family cannot be handed the wrong one.
+ *
+ * @template-covariant TUnit of Unit
+ * @api
+ */
+final readonly class Metric
+{
+    /**
+     * @param TUnit $unit
+     */
+    public function __construct(
+        public int|float $value,
+        public Unit $unit,
+    ) {}
+
+    /**
+     * The same amount in another unit of the same family.
+     *
+     * @template TTo of Unit
+     * @param TTo $unit
+     * @return self<TTo>
+     * @throws IncompatibleUnits When `$unit` belongs to a different family.
+     */
+    public function to(Unit $unit): self
+    {
+        return new self(Units::convert($this->value, $this->unit, $unit), $unit);
+    }
+
+    /**
+     * The same amount in the unit of its family that reads most compactly; see {@see UnitFamily::fit()}.
+     *
+     * @return self<TUnit>
+     */
+    public function compact(): self
+    {
+        return Units::compact($this->value, $this->unit);
+    }
+}
diff --git a/core/Metric/Unit.php b/core/Metric/Unit.php
new file mode 100644
index 00000000..baedcfc7
--- /dev/null
+++ b/core/Metric/Unit.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Metric;
+
+use Testo\Metric\Exception\IncompatibleUnits;
+
+/**
+ * The unit a {@see Metric} was measured in.
+ *
+ * The parent of every dimension enum ({@see \Testo\Core\Metric\Time}, {@see \Testo\Core\Metric\Memory}, {@see \Testo\Core\Metric\Percent}, {@see \Testo\Core\Metric\Scalar}), so a
+ * metric can name a unit from any family while a reporter still handles all of them through one type.
+ * Each family is one backed enum whose cases scale within it: the scale is declared with {@see Factor}
+ * on the cases and read by {@see Units}, and the {@see UnitConversion} trait implements this interface
+ * for such an enum. Converting between families is a reporter's job at its own boundary.
+ *
+ * @api
+ */
+interface Unit extends \BackedEnum
+{
+    /**
+     * How many base units of the family one of this unit is worth.
+     */
+    public function factor(): int|float;
+
+    /**
+     * An amount in this unit expressed in another unit of the same family.
+     *
+     * @throws IncompatibleUnits When `$to` belongs to a different family.
+     */
+    public function convert(int|float $value, Unit $to): int|float;
+}
diff --git a/core/Metric/UnitConversion.php b/core/Metric/UnitConversion.php
new file mode 100644
index 00000000..76159d03
--- /dev/null
+++ b/core/Metric/UnitConversion.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Metric;
+
+/**
+ * The {@see Unit} arithmetic for an enum that declares itself through {@see Dimension} and {@see Factor}.
+ *
+ * Everything is delegated to {@see Units}, so the enum contributes only its cases and attributes.
+ *
+ * @api
+ */
+trait UnitConversion
+{
+    public function factor(): int|float
+    {
+        return Units::factor($this);
+    }
+
+    public function convert(int|float $value, Unit $to): int|float
+    {
+        return Units::convert($value, $this, $to);
+    }
+}
diff --git a/core/Metric/UnitFamily.php b/core/Metric/UnitFamily.php
new file mode 100644
index 00000000..3e36a2a8
--- /dev/null
+++ b/core/Metric/UnitFamily.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Metric;
+
+/**
+ * Everything the metric core knows about one {@see Unit} enum, read once from its attributes.
+ *
+ * Obtained through {@see Units::family()}, which keeps one instance per enum so the reflection happens
+ * once per process.
+ *
+ * @api
+ */
+final readonly class UnitFamily
+{
+    /**
+     * @param class-string<Unit> $class
+     * @param non-empty-string $name The {@see Dimension} name.
+     * @param non-empty-list<Unit> $units Every case, smallest factor first, declaration order among equals.
+     * @param non-empty-array<non-empty-string, int|float> $factors {@see Factor} of each case, keyed by case name.
+     */
+    public function __construct(
+        public string $class,
+        public string $name,
+        public array $units,
+        public array $factors,
+    ) {}
+
+    public function factor(Unit $unit): int|float
+    {
+        return $this->factors[$unit->name];
+    }
+
+    /**
+     * The unit every factor is expressed in.
+     */
+    public function base(): Unit
+    {
+        return $this->units[0];
+    }
+
+    /**
+     * The unit in which a base-unit amount reads most compactly: the largest one it still reaches at
+     * least one of, so `1500` base units of a thousand-step family become `1.5` of the next unit up.
+     * Amounts below one of the smallest unit, and zero, stay in the smallest.
+     */
+    public function fit(int|float $baseValue): Unit
+    {
+        $magnitude = \abs($baseValue);
+        $fit = $this->base();
+        foreach ($this->units as $unit) {
+            $magnitude >= $this->factor($unit) and $fit = $unit;
+        }
+
+        return $fit;
+    }
+}
diff --git a/core/Metric/Units.php b/core/Metric/Units.php
new file mode 100644
index 00000000..0519de4b
--- /dev/null
+++ b/core/Metric/Units.php
@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Metric;
+
+use Testo\Common\Reflection;
+use Testo\Metric\Exception\IncompatibleUnits;
+use Testo\Metric\Exception\InvalidUnitDeclaration;
+
+/**
+ * Reads unit families off their attributes and does the arithmetic between units.
+ *
+ * Any enum implementing {@see Unit} is a family; its {@see Dimension} and {@see Factor} attributes are
+ * reflected once and kept for the rest of the process. A conversion is a plain ratio of factors, so an
+ * exact integer result stays an integer (`2` kilobytes are `2048` bytes, not `2048.0`) and only an
+ * inexact one becomes a float.
+ *
+ * @api
+ */
+final class Units
+{
+    /** @var array<class-string<Unit>, UnitFamily> */
+    private static array $families = [];
+
+    private function __construct() {}
+
+    /**
+     * @param Unit|class-string<Unit> $unit
+     * @throws InvalidUnitDeclaration
+     */
+    public static function family(Unit|string $unit): UnitFamily
+    {
+        $class = \is_string($unit) ? $unit : $unit::class;
+
+        return self::$families[$class] ??= self::reflect($class);
+    }
+
+    public static function factor(Unit $unit): int|float
+    {
+        return self::family($unit)->factor($unit);
+    }
+
+    /**
+     * @throws IncompatibleUnits When the units belong to different families.
+     */
+    public static function convert(int|float $value, Unit $from, Unit $to): int|float
+    {
+        $from::class === $to::class or throw IncompatibleUnits::between($from, $to);
+        if ($from === $to) {
+            return $value;
+        }
+
+        $family = self::family($from);
+        return self::ratio($value, $family->factor($from), $family->factor($to));
+    }
+
+    /**
+     * The same amount in the unit of its family that reads most compactly; see {@see UnitFamily::fit()}.
+     *
+     * @template TUnit of Unit
+     * @param TUnit $unit
+     * @return Metric<TUnit>
+     */
+    public static function compact(int|float $value, Unit $unit): Metric
+    {
+        $family = self::family($unit);
+        /** @var TUnit $fit */
+        $fit = $family->fit(self::convert($value, $unit, $family->base()));
+
+        return new Metric(self::convert($value, $unit, $fit), $fit);
+    }
+
+    /**
+     * `$value * $from / $to`, kept in integer arithmetic while every operand is an integer so an exact
+     * result stays an `int`; one float operand makes the whole ratio a float.
+     */
+    private static function ratio(int|float $value, int|float $from, int|float $to): int|float
+    {
+        if (\is_int($value) && \is_int($from) && \is_int($to)) {
+            return $value * $from / $to;
+        }
+
+        return (float) $value * (float) $from / (float) $to;
+    }
+
+    /**
+     * @param class-string $class
+     */
+    private static function reflect(string $class): UnitFamily
+    {
+        \enum_exists($class) && \is_subclass_of($class, Unit::class)
+            or throw InvalidUnitDeclaration::notAUnitEnum($class);
+
+        $enum = new \ReflectionEnum($class);
+        /** @var non-empty-string $name */
+        $name = (Reflection::fetchClassAttributes($enum, attributeClass: Dimension::class, limit: 1)[0] ?? null)
+            ?->newInstance()->name
+            ?? \strtolower($enum->getShortName());
+
+        /** @var array<non-empty-string, int|float> $factors */
+        $factors = [];
+        foreach (Reflection::fetchEnumCaseAttributes($enum, Factor::class) as $case => $attributes) {
+            $factor = ($attributes[0] ?? null)?->newInstance()->value ?? 1;
+            $factor > 0 or throw InvalidUnitDeclaration::nonPositiveFactor($class, $case, $factor);
+            $factors[$case] = $factor;
+        }
+        $factors === [] and throw InvalidUnitDeclaration::notAUnitEnum($class);
+
+        // `asort` is stable, so equal factors keep their declaration order.
+        $ordered = $factors;
+        \asort($ordered);
+        /** @var non-empty-list<Unit> $units */
+        $units = \array_map(
+            static fn(string $case): Unit => \constant("{$class}::{$case}"),
+            \array_keys($ordered),
+        );
+
+        /** @var class-string<Unit> $class */
+        return new UnitFamily($class, $name, $units, $factors);
+    }
+}
diff --git a/core/Output/JUnit/Internal/JUnitCaseNode.php b/core/Output/JUnit/Internal/JUnitCaseNode.php
index 4a9a984c..88fe8ebf 100644
--- a/core/Output/JUnit/Internal/JUnitCaseNode.php
+++ b/core/Output/JUnit/Internal/JUnitCaseNode.php
@@ -5,6 +5,8 @@
 namespace Testo\Output\JUnit\Internal;
 
 use Testo\Core\Value\Status;
+use Testo\Metric\Unit;
+use Testo\Metric\Metric;
 
 /**
  * Captured `<testcase>` payload produced from a single `TestResult`.
@@ -49,7 +51,7 @@ public function __construct(
          * benchmark counters, for tests that are benchmarks. Empty for an ordinary test, in which case
          * no `<properties>` element is written at all.
          *
-         * @var array<non-empty-string, int|float>
+         * @var array<non-empty-string, Metric<Unit>>
          */
         public array $properties = [],
     ) {}
diff --git a/core/Output/JUnit/Internal/JUnitWriter.php b/core/Output/JUnit/Internal/JUnitWriter.php
index 4729cf21..e0b45477 100644
--- a/core/Output/JUnit/Internal/JUnitWriter.php
+++ b/core/Output/JUnit/Internal/JUnitWriter.php
@@ -7,6 +7,7 @@
 use Internal\Path;
 use Testo\Core\Context\TestInfo;
 use Testo\Core\Context\TestResult;
+use Testo\Core\Metric\Scalar;
 use Testo\Core\Value\Status;
 use Testo\Output\Rendering\BenchMapper;
 use Testo\Output\Rendering\StackTrace;
@@ -452,10 +453,13 @@ private function writeCase(\XMLWriter $xml, JUnitCaseNode $case): void
         // knowledge to pick the numbers up.
         if ($case->properties !== []) {
             $xml->startElement('properties');
-            foreach ($case->properties as $name => $value) {
+            foreach ($case->properties as $name => $metric) {
                 $xml->startElement('property');
-                $xml->writeAttribute('name', $name);
-                $xml->writeAttribute('value', BenchMapper::formatMetric($value));
+                // A `<property>` carries no dimension of its own, so the unit rides on the name as one
+                // more key segment: `…mean.ms`, `…memory.B`. A bare count stays legible without one.
+                $unit = $metric->unit;
+                $xml->writeAttribute('name', $unit instanceof Scalar ? $name : "{$name}.{$unit->value}");
+                $xml->writeAttribute('value', BenchMapper::formatMetric($metric->value));
                 $xml->endElement();
             }
             $xml->endElement();
diff --git a/core/Output/Rendering/BenchMapper.php b/core/Output/Rendering/BenchMapper.php
index 4a19f6fe..7e922ab0 100644
--- a/core/Output/Rendering/BenchMapper.php
+++ b/core/Output/Rendering/BenchMapper.php
@@ -10,6 +10,12 @@
 use Testo\Bench\Dto\Report;
 use Testo\Bench\Dto\Report\Severity;
 use Testo\Bench\Dto\Snap;
+use Testo\Core\Metric\Memory;
+use Testo\Metric\Unit;
+use Testo\Metric\Metric;
+use Testo\Core\Metric\Percent;
+use Testo\Core\Metric\Scalar;
+use Testo\Core\Metric\Time;
 
 /**
  * Benchmark measurements as data rather than as the ASCII table the terminal prints.
@@ -77,40 +83,52 @@ public static function map(BenchResult $result): array
     }
 
     /**
-     * The same numbers flattened into `bench.<case>.<metric>` entries, for protocols that carry metrics
-     * as a flat list of named numbers rather than as a document.
+     * The same numbers flattened into `bench.<case>.<columnGroup>.<column>` entries, for protocols that
+     * carry metrics as a flat list of named numbers rather than as a document.
      *
-     * Unit is part of the key (`meanUs`, `rstdevPct`, `memoryBytes`) because a flat namespace has nowhere
-     * else to record it, and a consumer plotting these has no other way to label an axis.
+     * The four-segment key spells a grid a consumer can rebuild as a table — `bench` names it, the case
+     * is the row, and the last two segments place the value under a spanning column-group band matching
+     * the ASCII table the terminal prints: `Benchmark setup`, `Time results`, `Filtered results`,
+     * `Summary`. Every row carries every column, so the grid stays rectangular; a single-case result has
+     * no grid to form and reads as the flat list it degrades to.
      *
-     * @return array<non-empty-string, int|float>
+     * The unit rides on the {@see Metric}, not in the key, so each consumer reports it natively — the
+     * TeamCity number `type` it charts, a JUnit property name suffixed with the unit — instead of parsing
+     * it out of the leaf. Values stay in the unit the plugin measured them in (time in microseconds); a
+     * consumer that needs another converts at its own boundary. The column group says which family a
+     * number belongs to, and the same leaf may repeat across groups (`mean` under both `Time results` and
+     * `Filtered results`); the group segment tells them apart.
+     *
+     * @return array<non-empty-string, Metric<Unit>>
      */
     public static function metrics(BenchResult $result): array
     {
-        $metrics = [
-            'bench.iterations' => $result->cases === [] ? 0 : \count($result->cases[0]->iterations),
-        ];
+        $metrics = [];
 
         /** @var Line $line */
         foreach ($result->lines as $line) {
             $set = self::caseSet($result, $line->name);
-            $prefix = "bench.{$line->name}.";
-
-            $metrics[$prefix . 'calls'] = self::callsOf($set);
-            $metrics[$prefix . 'place'] = $line->place;
-            $metrics[$prefix . 'meanUs'] = $line->avg->value;
-            $metrics[$prefix . 'meanDiffPct'] = $line->avg->diff;
-            $metrics[$prefix . 'medianUs'] = $line->med->value;
-            $metrics[$prefix . 'medianDiffPct'] = $line->med->diff;
-            $metrics[$prefix . 'rstdevPct'] = $line->rstdev;
-            $metrics[$prefix . 'filteredMeanUs'] = $line->favg->value;
-            $metrics[$prefix . 'filteredMeanDiffPct'] = $line->favg->diff;
-            $metrics[$prefix . 'filteredRstdevPct'] = $line->frstdev;
-            $metrics[$prefix . 'rejected'] = $line->rejected;
-            $metrics[$prefix . 'memoryBytes'] = self::memoryOf($set);
+            $row = "bench.{$line->name}.";
+
+            $metrics[$row . 'Benchmark setup.iters'] = new Metric(self::iterationsOf($set), Scalar::Number);
+            $metrics[$row . 'Benchmark setup.calls'] = new Metric(self::callsOf($set), Scalar::Number);
+
+            $metrics[$row . 'Time results.mean'] = new Metric($line->avg->value, Time::Microseconds);
+            $metrics[$row . 'Time results.meanDiff'] = new Metric($line->avg->diff, Percent::Percent);
+            $metrics[$row . 'Time results.median'] = new Metric($line->med->value, Time::Microseconds);
+            $metrics[$row . 'Time results.medianDiff'] = new Metric($line->med->diff, Percent::Percent);
+            $metrics[$row . 'Time results.rstdev'] = new Metric($line->rstdev, Percent::Percent);
+
+            $metrics[$row . 'Filtered results.rejected'] = new Metric($line->rejected, Scalar::Number);
+            $metrics[$row . 'Filtered results.mean'] = new Metric($line->favg->value, Time::Microseconds);
+            $metrics[$row . 'Filtered results.meanDiff'] = new Metric($line->favg->diff, Percent::Percent);
+            $metrics[$row . 'Filtered results.rstdev'] = new Metric($line->frstdev, Percent::Percent);
+
+            $metrics[$row . 'Summary.place'] = new Metric($line->place, Scalar::Number);
+            $metrics[$row . 'Summary.memory'] = new Metric(self::memoryOf($set), Memory::Bytes);
         }
 
-        /** @var array<non-empty-string, int|float> */
+        /** @var array<non-empty-string, Metric<Unit>> */
         return $metrics;
     }
 
@@ -172,6 +190,14 @@ private static function caseSet(BenchResult $result, string $name): ?CaseSet
         return null;
     }
 
+    /**
+     * @return int<0, max>
+     */
+    private static function iterationsOf(?CaseSet $case): int
+    {
+        return \count($case?->iterations ?? []);
+    }
+
     /**
      * @return int<0, max>
      */
diff --git a/core/Output/Teamcity/Teamcity/Formatter.php b/core/Output/Teamcity/Teamcity/Formatter.php
index 108cfad9..75899651 100644
--- a/core/Output/Teamcity/Teamcity/Formatter.php
+++ b/core/Output/Teamcity/Teamcity/Formatter.php
@@ -339,7 +339,9 @@ public static function blockClosed(string $name): string
      * @param non-empty-string $testName Test the value belongs to
      * @param non-empty-string $name Metric key
      * @param non-empty-string $value Metric value, formatted for the declared type
-     * @param 'number'|'text'|'link'|'image'|'artifact' $type
+     * @param 'number'|'ms'|'bytes'|'percent'|'text'|'link'|'image'|'artifact' $type A number's dimension
+     *        (`ms`, `bytes`, `percent`) is carried here, where TeamCity charts it natively, rather than in
+     *        the value.
      * @return non-empty-string
      * @link https://www.jetbrains.com/help/teamcity/reporting-test-metadata.html
      */
diff --git a/core/Output/Teamcity/Teamcity/TeamcityLogger.php b/core/Output/Teamcity/Teamcity/TeamcityLogger.php
index 8399214a..ff7f05b4 100644
--- a/core/Output/Teamcity/Teamcity/TeamcityLogger.php
+++ b/core/Output/Teamcity/Teamcity/TeamcityLogger.php
@@ -451,9 +451,10 @@ private function logBenchMetrics(TestResult $result, ?string $overrideName = nul
         $name = $overrideName ?? $result->info->name;
         $identity = $result->info->identity;
 
-        foreach (BenchMapper::metrics($result->result) as $key => $value) {
+        foreach (BenchMapper::metrics($result->result) as $key => $metric) {
+            [$type, $value] = TeamcityMetricType::convert($metric);
             $this->publish(
-                Formatter::testMetadata($name, $key, BenchMapper::formatMetric($value), identity: $identity),
+                Formatter::testMetadata($name, $key, BenchMapper::formatMetric($value), $type->value, $identity),
             );
         }
     }
diff --git a/core/Output/Teamcity/Teamcity/TeamcityMetricType.php b/core/Output/Teamcity/Teamcity/TeamcityMetricType.php
new file mode 100644
index 00000000..0f29b6de
--- /dev/null
+++ b/core/Output/Teamcity/Teamcity/TeamcityMetricType.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Output\Teamcity\Teamcity;
+
+use Testo\Core\Metric\Memory;
+use Testo\Metric\Unit;
+use Testo\Metric\Metric;
+use Testo\Core\Metric\Percent;
+use Testo\Core\Metric\Scalar;
+use Testo\Core\Metric\Time;
+
+/**
+ * The number dimensions a TeamCity `testMetadata` message can carry, and the conversion of a Core
+ * {@see Metric} onto one of them.
+ *
+ * TeamCity charts a number by its `type` but knows only these four. A measurement in any richer unit is
+ * converted at this boundary — every {@see Time} unit down to milliseconds, its sole time dimension;
+ * every {@see Memory} unit down to bytes — so the source keeps its native precision for every other
+ * consumer.
+ *
+ * @link https://www.jetbrains.com/help/teamcity/reporting-test-metadata.html
+ * @internal
+ */
+enum TeamcityMetricType: string
+{
+    case Number = 'number';
+    case Milliseconds = 'ms';
+    case Bytes = 'bytes';
+    case Percent = 'percent';
+
+    /**
+     * The TeamCity type a metric maps to, and its value expressed in that type's unit.
+     *
+     * @param Metric<Unit> $metric
+     * @return array{self, int|float}
+     */
+    public static function convert(Metric $metric): array
+    {
+        $unit = $metric->unit;
+
+        return match (true) {
+            $unit instanceof Time => [self::Milliseconds, $metric->to(Time::Milliseconds)->value],
+            $unit instanceof Memory => [self::Bytes, $metric->to(Memory::Bytes)->value],
+            $unit instanceof Percent => [self::Percent, $metric->value],
+            $unit instanceof Scalar => [self::Number, $metric->value],
+            default => [self::Number, $metric->value],
+        };
+    }
+}
diff --git a/plugin/bench/tests/Self/BenchAttr.php b/plugin/bench/tests/Self/BenchAttr.php
index 38908eb3..6feed487 100644
--- a/plugin/bench/tests/Self/BenchAttr.php
+++ b/plugin/bench/tests/Self/BenchAttr.php
@@ -8,7 +8,7 @@
 use Testo\Filter\Group;
 use Testo\Inline\TestInline;
 
-#[Group('bench')]
+#[Group('bench', 'metadata')]
 final class BenchAttr
 {
     #[Bench(
diff --git a/plugin/test/src/Internal/TestMetadataInterceptor.php b/plugin/test/src/Internal/TestMetadataInterceptor.php
new file mode 100644
index 00000000..4cc63878
--- /dev/null
+++ b/plugin/test/src/Internal/TestMetadataInterceptor.php
@@ -0,0 +1,124 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Test\Internal;
+
+use Testo\Core\Context\TestInfo;
+use Testo\Core\Context\TestResult;
+use Testo\Core\Value\TestType;
+use Testo\Pipeline\Attribute\InterceptorOptions;
+use Testo\Pipeline\Middleware\TestRunInterceptor;
+use Testo\Test\MetadataType;
+use Testo\Test\TestMetadata;
+
+/**
+ * Emits a `##teamcity[testMetadata …]` service message for every {@see TestMetadata} on the test.
+ *
+ * The message must land between the test's `testStarted` and `testFinished`, so it is written after
+ * `$next()` — the test body has run and produced its output by then, which is what triggers
+ * `testStarted` — but before the pipeline finishes and the reporter closes the node with `testFinished`.
+ * It goes straight to the stream {@see \fwrite}, bypassing output capture, exactly as the built-in
+ * TeamCity logger does for benchmark metrics. The message is built here rather than through the core
+ * formatter so the plugin depends on nothing internal; the format is TeamCity's own stable protocol.
+ *
+ * @link https://www.jetbrains.com/help/teamcity/reporting-test-metadata.html
+ */
+#[InterceptorOptions(order: InterceptorOptions::ORDER_CLOSE_TO_TEST, testType: TestType::Test)]
+final readonly class TestMetadataInterceptor implements TestRunInterceptor
+{
+    /**
+     * @param resource $output Stream the metadata messages are written to.
+     */
+    public function __construct(private mixed $output = \STDOUT) {}
+
+    #[\Override]
+    public function runTest(TestInfo $info, callable $next): TestResult
+    {
+        try {
+            return $next($info);
+        } finally {
+            $this->publish($info);
+        }
+    }
+
+    private function publish(TestInfo $info): void
+    {
+        $reflection = $info->testDefinition->reflection;
+        $attributes = $reflection->getAttributes(TestMetadata::class);
+
+        if ($attributes === []) {
+            return;
+        }
+
+        $baseDir = \dirname($reflection->getFileName() ?: '.');
+        $flowId = (string) $info->identity->pipelineId;
+
+        foreach ($attributes as $attribute) {
+            $meta = $attribute->newInstance();
+            $value = $this->resolveValue($meta, $baseDir);
+
+            $value === '' or \fwrite($this->output, $this->format([
+                'testName' => $info->name,
+                'name' => $meta->name,
+                'type' => $meta->type->value,
+                'value' => $value,
+                'flowId' => $flowId,
+            ]) . "\n");
+        }
+    }
+
+    /**
+     * Resolves a local file reference against the test's directory; a URL or an absolute path passes
+     * through untouched, as do the non-file types.
+     */
+    private function resolveValue(TestMetadata $meta, string $baseDir): string
+    {
+        $isFileType = $meta->type === MetadataType::Image || $meta->type === MetadataType::Artifact;
+
+        return match (true) {
+            !$isFileType,
+            $this->isUrl($meta->value),
+            $this->isAbsolute($meta->value) => $meta->value,
+            default => $baseDir . \DIRECTORY_SEPARATOR . \strtr($meta->value, '/', \DIRECTORY_SEPARATOR),
+        };
+    }
+
+    /**
+     * Builds a `##teamcity[testMetadata …]` service message from already-resolved attribute values.
+     *
+     * @param array<non-empty-string, string> $attributes
+     * @return non-empty-string
+     */
+    private function format(array $attributes): string
+    {
+        $parts = '';
+        foreach ($attributes as $key => $value) {
+            $parts .= " {$key}='{$this->escape($value)}'";
+        }
+
+        return "##teamcity[testMetadata{$parts}]";
+    }
+
+    /**
+     * Escapes a value per the TeamCity service-message rules.
+     */
+    private function escape(string $value): string
+    {
+        return \str_replace(
+            ['|', "'", "\n", "\r", '[', ']'],
+            ['||', "|'", '|n', '|r', '|[', '|]'],
+            $value,
+        );
+    }
+
+    private function isUrl(string $value): bool
+    {
+        return \preg_match('#^[a-z][a-z0-9+.-]*://#i', $value) === 1;
+    }
+
+    private function isAbsolute(string $value): bool
+    {
+        return $value !== '' && ($value[0] === '/' || \preg_match('#^[a-z]:[\\\\/]#i', $value) === 1);
+    }
+}
diff --git a/plugin/test/src/MetadataType.php b/plugin/test/src/MetadataType.php
new file mode 100644
index 00000000..9d008040
--- /dev/null
+++ b/plugin/test/src/MetadataType.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Test;
+
+/**
+ * TeamCity `testMetadata` value types.
+ *
+ * The set a CI server and an IDE know how to render: a number it charts across builds — dimensionless or
+ * carrying one of TeamCity's measurement dimensions (`ms`, `bytes`, `percent`, which format the graph
+ * axis) — plain text, a clickable link, an inline image, and a downloadable artifact.
+ *
+ * @link https://www.jetbrains.com/help/teamcity/reporting-test-metadata.html
+ * @api
+ */
+enum MetadataType: string
+{
+    case Number = 'number';
+    case Milliseconds = 'ms';
+    case Bytes = 'bytes';
+    case Percent = 'percent';
+    case Text = 'text';
+    case Link = 'link';
+    case Image = 'image';
+    case Artifact = 'artifact';
+}
diff --git a/plugin/test/src/TestMetadata.php b/plugin/test/src/TestMetadata.php
new file mode 100644
index 00000000..f418ea57
--- /dev/null
+++ b/plugin/test/src/TestMetadata.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Test;
+
+use Testo\Test\Internal\TestMetadataInterceptor;
+
+/**
+ * Attaches one `testMetadata` value to a test, reported by {@see TestMetadataInterceptor}.
+ *
+ * Repeatable — stack several to attach a chart's worth of numbers, an image and its source link, and so
+ * on. For {@see MetadataType::Image} and {@see MetadataType::Artifact} a relative `$value` is resolved
+ * against the directory of the test file, so a fixture shipped next to the test is found; a URL or an
+ * absolute path is emitted verbatim.
+ *
+ * @api
+ */
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
+final readonly class TestMetadata
+{
+    public function __construct(
+        public string $name,
+        public string $value,
+        public MetadataType $type = MetadataType::Number,
+    ) {}
+}
diff --git a/plugin/test/src/TestPlugin.php b/plugin/test/src/TestPlugin.php
index f8969d25..0ec53eb0 100644
--- a/plugin/test/src/TestPlugin.php
+++ b/plugin/test/src/TestPlugin.php
@@ -8,10 +8,11 @@
 use Testo\Common\PluginConfigurator;
 use Testo\Pipeline\InterceptorCollector;
 use Testo\Test;
+use Testo\Test\Internal\TestMetadataInterceptor;
 use Testo\Test\Internal\TestoAttributesLocatorInterceptor;
 
 /**
- * Find tests by the {@see Test} attribute.
+ * Find tests by the {@see Test} attribute, and report any {@see TestMetadata} they declare.
  *
  * @api
  */
@@ -20,6 +21,8 @@
     #[\Override]
     public function configure(Container $container): void
     {
-        $container->get(InterceptorCollector::class)->addInterceptor(new TestoAttributesLocatorInterceptor());
+        $collector = $container->get(InterceptorCollector::class);
+        $collector->addInterceptor(new TestoAttributesLocatorInterceptor());
+        $collector->addInterceptor(new TestMetadataInterceptor());
     }
 }
diff --git a/plugin/test/tests/Unit/Fixture/TestClassWithMetadata.php b/plugin/test/tests/Unit/Fixture/TestClassWithMetadata.php
new file mode 100644
index 00000000..cb5a2f86
--- /dev/null
+++ b/plugin/test/tests/Unit/Fixture/TestClassWithMetadata.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Test\Unit\Fixture;
+
+use Testo\Test\MetadataType;
+use Testo\Test\TestMetadata;
+
+/**
+ * Fixture for {@see \Tests\Test\Unit\Internal\TestMetadataInterceptorTest}: methods carrying (and not
+ * carrying) {@see TestMetadata}. Excluded from discovery — driven by reflection from the test.
+ */
+final class TestClassWithMetadata
+{
+    #[TestMetadata(name: 'score', value: '97.3', type: MetadataType::Number)]
+    #[TestMetadata(name: 'chart', value: 'chart.png', type: MetadataType::Image)]
+    public function reports(): void {}
+
+    public function noMetadata(): void {}
+}
diff --git a/plugin/test/tests/Unit/Internal/TestMetadataInterceptorTest.php b/plugin/test/tests/Unit/Internal/TestMetadataInterceptorTest.php
new file mode 100644
index 00000000..4b19172b
--- /dev/null
+++ b/plugin/test/tests/Unit/Internal/TestMetadataInterceptorTest.php
@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Test\Unit\Internal;
+
+use Internal\Path;
+use Testo\Assert;
+use Testo\Codecov\Covers;
+use Testo\Core\Context\CaseInfo;
+use Testo\Core\Context\Identity\SuiteIdentity;
+use Testo\Core\Context\TestInfo;
+use Testo\Core\Context\TestResult;
+use Testo\Core\Definition\CaseDefinition;
+use Testo\Core\Definition\TestDefinition;
+use Testo\Core\Value\Status;
+use Testo\Test;
+use Testo\Test\Internal\TestMetadataInterceptor;
+use Tests\Test\Unit\Fixture\TestClassWithMetadata;
+
+#[Test]
+#[Covers(TestMetadataInterceptor::class)]
+final class TestMetadataInterceptorTest
+{
+    public function emitsATestMetadataMessagePerAttribute(): void
+    {
+        $output = self::capture('reports');
+
+        Assert::string($output)->contains('##teamcity[testMetadata');
+        Assert::string($output)->contains("testName='reports'");
+        Assert::string($output)->contains("name='score'");
+        Assert::string($output)->contains("type='number'");
+        Assert::string($output)->contains("value='97.3'");
+        // The pipeline id groups the message onto the test's flow.
+        Assert::string($output)->contains('flowId=');
+    }
+
+    public function resolvesARelativeFileAgainstTheTestDirectory(): void
+    {
+        $output = self::capture('reports');
+
+        // A relative image path becomes absolute, rooted at the fixture's own directory.
+        $dir = \dirname((string) (new \ReflectionClass(TestClassWithMetadata::class))->getFileName());
+        Assert::string($output)->contains("type='image'");
+        Assert::string($output)->contains($dir . \DIRECTORY_SEPARATOR . 'chart.png');
+    }
+
+    public function emitsNothingForATestWithoutMetadata(): void
+    {
+        Assert::same(self::capture('noMetadata'), '');
+    }
+
+    /**
+     * Runs the interceptor over one fixture method and returns what it wrote to its stream.
+     *
+     * @param non-empty-string $method
+     */
+    private static function capture(string $method): string
+    {
+        $stream = \fopen('php://memory', 'rb+');
+        \assert($stream !== false);
+
+        $interceptor = new TestMetadataInterceptor($stream);
+        $interceptor->runTest(
+            self::infoFor($method),
+            static fn(TestInfo $info): TestResult => new TestResult(info: $info, status: Status::Passed),
+        );
+
+        \rewind($stream);
+        $contents = \stream_get_contents($stream);
+        \fclose($stream);
+
+        return $contents === false ? '' : $contents;
+    }
+
+    /**
+     * @param non-empty-string $method
+     */
+    private static function infoFor(string $method): TestInfo
+    {
+        $reflection = new \ReflectionClass(TestClassWithMetadata::class);
+
+        return new TestInfo(
+            name: $method,
+            caseInfo: new CaseInfo(
+                suiteIdentity: new SuiteIdentity('Test/Unit'),
+                definition: new CaseDefinition(
+                    name: TestClassWithMetadata::class,
+                    type: 'test',
+                    file: Path::create((string) $reflection->getFileName()),
+                    reflection: $reflection,
+                ),
+            ),
+            testDefinition: new TestDefinition(new \ReflectionMethod(TestClassWithMetadata::class, $method)),
+        );
+    }
+}
diff --git a/testo.php b/testo.php
index e4ceb9eb..b798f835 100644
--- a/testo.php
+++ b/testo.php
@@ -73,6 +73,7 @@
         require 'tests/Testo/suites.php',
         require 'tests/Application/suites.php',
         require 'tests/Core/suites.php',
+        require 'tests/Metric/suites.php',
         require 'tests/Common/suites.php',
         require 'tests/Output/suites.php',
         require 'tests/Tokenizer/suites.php',
diff --git a/tests/Common/Stub/CaseMarkerAttribute.php b/tests/Common/Stub/CaseMarkerAttribute.php
new file mode 100644
index 00000000..9b8285a6
--- /dev/null
+++ b/tests/Common/Stub/CaseMarkerAttribute.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Common\Stub;
+
+#[\Attribute(\Attribute::TARGET_CLASS_CONSTANT | \Attribute::IS_REPEATABLE)]
+final class CaseMarkerAttribute
+{
+    public function __construct(
+        public readonly string $label = '',
+    ) {}
+}
diff --git a/tests/Common/Stub/MarkedEnum.php b/tests/Common/Stub/MarkedEnum.php
new file mode 100644
index 00000000..85cd7230
--- /dev/null
+++ b/tests/Common/Stub/MarkedEnum.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Common\Stub;
+
+enum MarkedEnum: string
+{
+    #[CaseMarkerAttribute('first')]
+    case Marked = 'marked';
+    case Plain = 'plain';
+
+    #[CaseMarkerAttribute('second')]
+    #[CaseMarkerAttribute('third')]
+    case Repeated = 'repeated';
+}
diff --git a/tests/Common/Unit/ReflectionTest.php b/tests/Common/Unit/ReflectionTest.php
index e1709f86..2823f406 100644
--- a/tests/Common/Unit/ReflectionTest.php
+++ b/tests/Common/Unit/ReflectionTest.php
@@ -11,10 +11,12 @@
 use Tests\Common\Stub\AnotherMarkerAttribute;
 use Tests\Common\Stub\AttributedChild;
 use Tests\Common\Stub\BaseClass;
+use Tests\Common\Stub\CaseMarkerAttribute;
 use Tests\Common\Stub\ChildClass;
 use Tests\Common\Stub\ClassWithoutMarkedMethods;
 use Tests\Common\Stub\ClassWithTrait;
 use Tests\Common\Stub\InnerTrait;
+use Tests\Common\Stub\MarkedEnum;
 use Tests\Common\Stub\MarkerAttribute;
 use Tests\Common\Stub\MergePolicyChild;
 use Tests\Common\Stub\ReflectionCallStackHelper;
@@ -364,4 +366,32 @@ public function getAttributesFromCallStack_withNullAttributeClass_returnsAllAttr
 
         Assert::true(\count($attrs) >= 1);
     }
+
+    // --- fetchEnumCaseAttributes ---
+
+    public function fetchEnumCaseAttributes_listsEveryCaseInDeclarationOrder(): void
+    {
+        $attributes = Reflection::fetchEnumCaseAttributes(MarkedEnum::class, CaseMarkerAttribute::class);
+
+        Assert::same(\array_keys($attributes), ['Marked', 'Plain', 'Repeated']);
+        Assert::same($attributes['Plain'], []);
+        Assert::same(
+            \array_map(static fn(\ReflectionAttribute $a) => $a->newInstance()->label, $attributes['Repeated']),
+            ['second', 'third'],
+        );
+    }
+
+    public function fetchEnumCaseAttributes_acceptsReflectionEnumInstance(): void
+    {
+        $attributes = Reflection::fetchEnumCaseAttributes(new \ReflectionEnum(MarkedEnum::class), CaseMarkerAttribute::class);
+
+        Assert::same($attributes['Marked'][0]->newInstance()->label, 'first');
+    }
+
+    public function fetchEnumCaseAttributes_withNullAttributeClass_returnsAllAttributes(): void
+    {
+        $attributes = Reflection::fetchEnumCaseAttributes(MarkedEnum::class);
+
+        Assert::same(\array_map(\count(...), $attributes), ['Marked' => 1, 'Plain' => 0, 'Repeated' => 2]);
+    }
 }
diff --git a/tests/Core/Metric/BuiltinUnitsTest.php b/tests/Core/Metric/BuiltinUnitsTest.php
new file mode 100644
index 00000000..e9b881e9
--- /dev/null
+++ b/tests/Core/Metric/BuiltinUnitsTest.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Core\Metric;
+
+use Testo\Assert;
+use Testo\Codecov\Covers;
+use Testo\Core\Metric\Memory;
+use Testo\Core\Metric\Percent;
+use Testo\Core\Metric\Scalar;
+use Testo\Core\Metric\Time;
+use Testo\Metric\UnitConversion;
+use Testo\Metric\Units;
+use Testo\Metric\Unit;
+use Testo\Data\DataSet;
+use Testo\Test;
+
+#[Test]
+#[Covers(Time::class)]
+#[Covers(Memory::class)]
+#[Covers(Percent::class)]
+#[Covers(Scalar::class)]
+#[Covers(UnitConversion::class)]
+final class BuiltinUnitsTest
+{
+    #[DataSet([Time::Nanoseconds, 1])]
+    #[DataSet([Time::Microseconds, 1_000])]
+    #[DataSet([Time::Milliseconds, 1_000_000])]
+    #[DataSet([Time::Seconds, 1_000_000_000])]
+    #[DataSet([Memory::Bytes, 1])]
+    #[DataSet([Memory::Kibibytes, 1024])]
+    #[DataSet([Memory::Mebibytes, 1_048_576])]
+    #[DataSet([Memory::Gibibytes, 1_073_741_824])]
+    #[DataSet([Percent::Percent, 1])]
+    #[DataSet([Scalar::Number, 1])]
+    public function factorsMatchTheUnitScale(Unit $unit, int $factor): void
+    {
+        Assert::same($unit->factor(), $factor);
+    }
+
+    #[DataSet([Time::class, 'time', Time::Nanoseconds])]
+    #[DataSet([Memory::class, 'memory', Memory::Bytes])]
+    #[DataSet([Percent::class, 'percent', Percent::Percent])]
+    #[DataSet([Scalar::class, 'number', Scalar::Number])]
+    public function familiesAreNamedAndBased(string $class, string $name, Unit $base): void
+    {
+        $family = Units::family($class);
+
+        Assert::same($family->name, $name);
+        Assert::same($family->base(), $base);
+    }
+}
diff --git a/tests/Core/suites.php b/tests/Core/suites.php
index a43a304e..a2b4f468 100644
--- a/tests/Core/suites.php
+++ b/tests/Core/suites.php
@@ -18,6 +18,12 @@
             include: [__DIR__ . '/Log'],
         ),
     ),
+    new SuiteConfig(
+        name: 'Core/Metric',
+        location: new FinderConfig(
+            include: [__DIR__ . '/Metric'],
+        ),
+    ),
     new SuiteConfig(
         name: 'Core/Value',
         location: new FinderConfig(
diff --git a/tests/Metric/Fixture/Distance.php b/tests/Metric/Fixture/Distance.php
new file mode 100644
index 00000000..b170dd65
--- /dev/null
+++ b/tests/Metric/Fixture/Distance.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Metric\Fixture;
+
+use Testo\Metric\Dimension;
+use Testo\Metric\Factor;
+use Testo\Metric\UnitConversion;
+use Testo\Metric\Unit;
+
+/**
+ * A family declared out of order and with a fractional factor, so the ordering and float arithmetic of
+ * the metric core are exercised rather than assumed from the built-in families.
+ */
+#[Dimension('distance')]
+enum Distance: string implements Unit
+{
+    use UnitConversion;
+
+    #[Factor(1_000)]
+    case Kilometers = 'km';
+
+    #[Factor(0.01)]
+    case Centimeters = 'cm';
+    case Meters = 'm';
+}
diff --git a/tests/Metric/Fixture/NegativeFactor.php b/tests/Metric/Fixture/NegativeFactor.php
new file mode 100644
index 00000000..c9977ecd
--- /dev/null
+++ b/tests/Metric/Fixture/NegativeFactor.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Metric\Fixture;
+
+use Testo\Metric\Factor;
+use Testo\Metric\UnitConversion;
+use Testo\Metric\Unit;
+
+enum NegativeFactor: string implements Unit
+{
+    use UnitConversion;
+    case Base = 'base';
+
+    #[Factor(-2)]
+    case Broken = 'broken';
+}
diff --git a/tests/Metric/Fixture/NotAUnit.php b/tests/Metric/Fixture/NotAUnit.php
new file mode 100644
index 00000000..ee20a3aa
--- /dev/null
+++ b/tests/Metric/Fixture/NotAUnit.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Metric\Fixture;
+
+/**
+ * A backed enum that never joined the {@see \Testo\Metric\Unit} contract.
+ */
+enum NotAUnit: string
+{
+    case Whatever = 'whatever';
+}
diff --git a/tests/Metric/Fixture/Plain.php b/tests/Metric/Fixture/Plain.php
new file mode 100644
index 00000000..a5efb0a9
--- /dev/null
+++ b/tests/Metric/Fixture/Plain.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Metric\Fixture;
+
+use Testo\Metric\UnitConversion;
+use Testo\Metric\Unit;
+
+/**
+ * A family that declares nothing: no dimension name and no factors.
+ */
+enum Plain: string implements Unit
+{
+    use UnitConversion;
+    case One = 'one';
+    case Other = 'other';
+}
diff --git a/tests/Metric/MetricTest.php b/tests/Metric/MetricTest.php
new file mode 100644
index 00000000..f867a0aa
--- /dev/null
+++ b/tests/Metric/MetricTest.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Metric;
+
+use Testo\Assert;
+use Testo\Assert\ExpectException;
+use Testo\Codecov\Covers;
+use Testo\Metric\Exception\IncompatibleUnits;
+use Testo\Core\Metric\Memory;
+use Testo\Metric\Metric;
+use Testo\Core\Metric\Time;
+use Testo\Test;
+
+#[Test]
+#[Covers(Metric::class)]
+final class MetricTest
+{
+    public function toReturnsANewMetricInTheRequestedUnit(): void
+    {
+        $metric = new Metric(1_500, Time::Microseconds);
+
+        $converted = $metric->to(Time::Milliseconds);
+
+        Assert::same($converted->value, 1.5);
+        Assert::same($converted->unit, Time::Milliseconds);
+        Assert::same($metric->value, 1_500);
+    }
+
+    #[ExpectException(IncompatibleUnits::class)]
+    public function toAnotherFamilyIsRefused(): void
+    {
+        (new Metric(1, Time::Seconds))->to(Memory::Bytes);
+    }
+
+    public function compactRescalesToTheMostReadableUnit(): void
+    {
+        Assert::equals((new Metric(2_048, Memory::Bytes))->compact(), new Metric(2, Memory::Kibibytes));
+        Assert::equals((new Metric(0.25, Time::Seconds))->compact(), new Metric(250.0, Time::Milliseconds));
+    }
+}
diff --git a/tests/Metric/UnitsTest.php b/tests/Metric/UnitsTest.php
new file mode 100644
index 00000000..115e823f
--- /dev/null
+++ b/tests/Metric/UnitsTest.php
@@ -0,0 +1,152 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Metric;
+
+use Testo\Assert;
+use Testo\Assert\ExpectException;
+use Testo\Codecov\Covers;
+use Testo\Metric\Exception\IncompatibleUnits;
+use Testo\Metric\Exception\InvalidUnitDeclaration;
+use Testo\Core\Metric\Memory;
+use Testo\Metric\UnitFamily;
+use Testo\Metric\Units;
+use Testo\Metric\Metric;
+use Testo\Core\Metric\Time;
+use Testo\Data\DataSet;
+use Testo\Test;
+use Tests\Metric\Fixture\Distance;
+use Tests\Metric\Fixture\NegativeFactor;
+use Tests\Metric\Fixture\NotAUnit;
+use Tests\Metric\Fixture\Plain;
+
+#[Test]
+#[Covers(Units::class)]
+#[Covers(UnitFamily::class)]
+#[Covers(IncompatibleUnits::class)]
+#[Covers(InvalidUnitDeclaration::class)]
+final class UnitsTest
+{
+    public function familyReadsDimensionAndFactorsFromAttributes(): void
+    {
+        $family = Units::family(Distance::class);
+
+        Assert::same($family->class, Distance::class);
+        Assert::same($family->name, 'distance');
+        Assert::same($family->factors, ['Kilometers' => 1_000, 'Centimeters' => 0.01, 'Meters' => 1]);
+    }
+
+    public function unitsAreOrderedByFactorRegardlessOfDeclaration(): void
+    {
+        $family = Units::family(Distance::class);
+
+        Assert::same($family->units, [Distance::Centimeters, Distance::Meters, Distance::Kilometers]);
+        Assert::same($family->base(), Distance::Centimeters);
+    }
+
+    public function familyWithoutAttributesFallsBackToClassNameAndUnitFactors(): void
+    {
+        $family = Units::family(Plain::class);
+
+        Assert::same($family->name, 'plain');
+        Assert::same($family->factors, ['One' => 1, 'Other' => 1]);
+        // Equal factors keep declaration order, so the first declared case is the base.
+        Assert::same($family->base(), Plain::One);
+    }
+
+    public function familyIsReflectedOnceAndReused(): void
+    {
+        $first = Units::family(Time::class);
+
+        Assert::same(Units::family(Time::class), $first);
+        Assert::same(Units::family(Time::Seconds), $first);
+    }
+
+    public function forgottenFamilyIsReflectedAgain(): void
+    {
+        $before = Units::family(Plain::class);
+        (new \ReflectionProperty(Units::class, 'families'))->setValue(null, []);
+
+        Assert::notSame(Units::family(Plain::class), $before);
+    }
+
+    #[DataSet([Distance::Centimeters, 0.01])]
+    #[DataSet([Distance::Meters, 1])]
+    #[DataSet([Distance::Kilometers, 1_000])]
+    public function factorOfUnit(Distance $unit, int|float $expected): void
+    {
+        Assert::same(Units::factor($unit), $expected);
+        Assert::same($unit->factor(), $expected);
+    }
+
+    public function convertKeepsExactIntegerResultsIntegral(): void
+    {
+        Assert::same(Units::convert(2, Memory::Kibibytes, Memory::Bytes), 2048);
+        Assert::same(Units::convert(3, Time::Seconds, Time::Microseconds), 3_000_000);
+        Assert::same(Units::convert(2048, Memory::Bytes, Memory::Kibibytes), 2);
+    }
+
+    public function convertTurnsInexactResultsIntoFloats(): void
+    {
+        Assert::same(Units::convert(1_500, Time::Microseconds, Time::Milliseconds), 1.5);
+        Assert::same(Units::convert(1, Memory::Bytes, Memory::Kibibytes), 1 / 1024);
+    }
+
+    public function convertHandlesFractionalFactors(): void
+    {
+        Assert::same(Units::convert(250, Distance::Centimeters, Distance::Meters), 2.5);
+        Assert::same(Units::convert(2, Distance::Kilometers, Distance::Centimeters), 200_000.0);
+    }
+
+    public function convertToTheSameUnitReturnsTheValueUntouched(): void
+    {
+        Assert::same(Units::convert(42, Time::Seconds, Time::Seconds), 42);
+        Assert::same(Units::convert(4.2, Time::Seconds, Time::Seconds), 4.2);
+    }
+
+    public function convertIsAvailableOnTheUnitItself(): void
+    {
+        Assert::same(Time::Milliseconds->convert(1.5, Time::Microseconds), 1_500.0);
+    }
+
+    #[ExpectException(IncompatibleUnits::class)]
+    public function convertAcrossFamiliesIsRefused(): void
+    {
+        Units::convert(1, Time::Seconds, Memory::Bytes);
+    }
+
+    #[DataSet([1_500, Time::Microseconds, new Metric(1.5, Time::Milliseconds)], 'scales up to the next unit')]
+    #[DataSet([2.5, Time::Seconds, new Metric(2.5, Time::Seconds)], 'already compact')]
+    #[DataSet([999, Time::Nanoseconds, new Metric(999, Time::Nanoseconds)], 'below the next unit stays')]
+    #[DataSet([1_000, Time::Nanoseconds, new Metric(1, Time::Microseconds)], 'exactly one of the next unit moves')]
+    #[DataSet([0.5, Time::Microseconds, new Metric(500.0, Time::Nanoseconds)], 'below one of the current unit scales down')]
+    #[DataSet([0, Time::Seconds, new Metric(0, Time::Nanoseconds)], 'zero lands in the base')]
+    #[DataSet([-3_000_000, Time::Microseconds, new Metric(-3, Time::Seconds)], 'sign is ignored when fitting')]
+    #[DataSet([3 * 1024 ** 3, Memory::Bytes, new Metric(3, Memory::Gibibytes)], 'memory scales by 1024')]
+    #[DataSet([1, Plain::Other, new Metric(1, Plain::Other)], 'equal factors keep the given unit')]
+    public function compactPicksTheLargestUnitTheValueReaches(int|float $value, $unit, Metric $expected): void
+    {
+        Assert::equals(Units::compact($value, $unit), $expected);
+    }
+
+    #[ExpectException(InvalidUnitDeclaration::class)]
+    public function nonPositiveFactorIsRejected(): void
+    {
+        Units::family(NegativeFactor::class);
+    }
+
+    #[ExpectException(InvalidUnitDeclaration::class)]
+    public function enumOutsideTheUnitContractIsRejected(): void
+    {
+        /** @phpstan-ignore-next-line */
+        Units::family(NotAUnit::class);
+    }
+
+    #[ExpectException(InvalidUnitDeclaration::class)]
+    public function nonEnumClassIsRejected(): void
+    {
+        /** @phpstan-ignore-next-line */
+        Units::family(\stdClass::class);
+    }
+}
diff --git a/tests/Metric/suites.php b/tests/Metric/suites.php
new file mode 100644
index 00000000..b15d16a4
--- /dev/null
+++ b/tests/Metric/suites.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+use Testo\Application\Config\FinderConfig;
+use Testo\Application\Config\SuiteConfig;
+
+/**
+ * Test suites for the Metric component.
+ */
+return [
+    new SuiteConfig(
+        name: 'Metric',
+        location: new FinderConfig(
+            include: [__DIR__],
+            exclude: [__DIR__ . '/Fixture'],
+        ),
+    ),
+];
diff --git a/tests/Output/Unit/JUnit/JUnitWriterTest.php b/tests/Output/Unit/JUnit/JUnitWriterTest.php
index 77a4e4cc..617853e6 100644
--- a/tests/Output/Unit/JUnit/JUnitWriterTest.php
+++ b/tests/Output/Unit/JUnit/JUnitWriterTest.php
@@ -197,9 +197,11 @@ public function benchmarkTestCarriesItsMeasurementsAsProperties(): void
         foreach ($properties->property as $property) {
             $byName[(string) $property['name']] = (string) $property['value'];
         }
-        Assert::same($byName['bench.iterations'], '1');
-        Assert::same($byName['bench.shift.meanUs'], '5.1');
-        Assert::same($byName['bench.shift.calls'], '20');
+        Assert::same($byName['bench.shift.Benchmark setup.iters'], '1');
+        // The dimension has no `type` attribute to live in here, so it rides on the property name — and
+        // JUnit keeps the native microseconds rather than TeamCity's converted milliseconds.
+        Assert::same($byName['bench.shift.Time results.mean.us'], '5.1');
+        Assert::same($byName['bench.shift.Benchmark setup.calls'], '20');
     }
 
     #[Covers(JUnitWriter::class)]
diff --git a/tests/Output/Unit/Rendering/BenchMapperTest.php b/tests/Output/Unit/Rendering/BenchMapperTest.php
index 28a16518..e14ec007 100644
--- a/tests/Output/Unit/Rendering/BenchMapperTest.php
+++ b/tests/Output/Unit/Rendering/BenchMapperTest.php
@@ -12,6 +12,10 @@
 use Testo\Bench\Dto\Snap;
 use Testo\Bench\Dto\ValueRel;
 use Testo\Codecov\Covers;
+use Testo\Core\Metric\Memory;
+use Testo\Core\Metric\Percent;
+use Testo\Core\Metric\Scalar;
+use Testo\Core\Metric\Time;
 use Testo\Output\Rendering\BenchMapper;
 use Testo\Test;
 
@@ -70,30 +74,42 @@ public function mapFlattensDiagnosticsWithTheShortReportName(): void
         Assert::string($diagnostics[0]['advice'])->contains('Increase');
     }
 
-    public function metricsNameTheUnitInEveryKey(): void
+    public function metricsCarryTheUnitOnTheMetricNotInTheLeaf(): void
     {
         $metrics = BenchMapper::metrics(self::result());
 
-        // A flat namespace has nowhere else to record the unit, so it lives in the key. The unit-less
-        // spelling must not leak through alongside it.
-        Assert::true(\array_key_exists('bench.shift.meanUs', $metrics));
-        Assert::false(\array_key_exists('bench.shift.mean', $metrics));
-        Assert::true(\array_key_exists('bench.shift.rstdevPct', $metrics));
-        Assert::true(\array_key_exists('bench.shift.memoryBytes', $metrics));
+        // The dimension rides on the Metric so a consumer reports it natively; the leaf is unit-free.
+        Assert::same($metrics['bench.shift.Time results.mean']->unit, Time::Microseconds);
+        Assert::same($metrics['bench.shift.Time results.rstdev']->unit, Percent::Percent);
+        Assert::same($metrics['bench.shift.Summary.memory']->unit, Memory::Bytes);
+        Assert::same($metrics['bench.shift.Summary.place']->unit, Scalar::Number);
+
+        // The unit-bearing spellings must not leak back into the key.
+        Assert::false(\array_key_exists('bench.shift.Time results.meanUs', $metrics));
+        Assert::false(\array_key_exists('bench.shift.Summary.memoryBytes', $metrics));
+    }
+
+    public function metricsKeepTimeInItsNativeMicroseconds(): void
+    {
+        $metrics = BenchMapper::metrics(self::result());
+
+        // The source keeps microseconds; a consumer that needs another unit converts at its own boundary.
+        // The same leaf lives under two bands; the group segment keeps them apart.
+        Assert::same($metrics['bench.shift.Time results.mean']->value, 5.1);
+        Assert::same($metrics['bench.shift.Filtered results.mean']->value, 5.05);
     }
 
     public function metricsCarryTheSameNumbersAsTheMap(): void
     {
         $metrics = BenchMapper::metrics(self::result());
 
-        Assert::same($metrics['bench.iterations'], 2);
-        Assert::same($metrics['bench.shift.calls'], 20);
-        Assert::same($metrics['bench.shift.place'], 1);
-        Assert::same($metrics['bench.shift.meanUs'], 5.1);
-        Assert::same($metrics['bench.shift.memoryBytes'], 300);
-        Assert::same($metrics['bench.push.memoryBytes'], 0);
-        Assert::same($metrics['bench.push.rejected'], 1);
-        Assert::same($metrics['bench.push.rstdevPct'], 12.0);
+        Assert::same($metrics['bench.shift.Benchmark setup.iters']->value, 2);
+        Assert::same($metrics['bench.shift.Benchmark setup.calls']->value, 20);
+        Assert::same($metrics['bench.shift.Summary.place']->value, 1);
+        Assert::same($metrics['bench.shift.Summary.memory']->value, 300);
+        Assert::same($metrics['bench.push.Summary.memory']->value, 0);
+        Assert::same($metrics['bench.push.Filtered results.rejected']->value, 1);
+        Assert::same($metrics['bench.push.Time results.rstdev']->value, 12.0);
     }
 
     public function anEmptyResultProducesNoCasesAndNoDiagnostics(): void
@@ -105,9 +121,10 @@ public function anEmptyResultProducesNoCasesAndNoDiagnostics(): void
         Assert::same($map['diagnostics'], []);
     }
 
-    public function anEmptyResultStillReportsItsIterationCounter(): void
+    public function anEmptyResultReportsNoMetrics(): void
     {
-        Assert::same(BenchMapper::metrics(new BenchResult([], [])), ['bench.iterations' => 0]);
+        // No case, no row — a grid with nothing to place, so nothing is emitted.
+        Assert::same(BenchMapper::metrics(new BenchResult([], [])), []);
     }
 
     public function formatMetricKeepsAnIntegerExact(): void
diff --git a/tests/Output/Unit/Teamcity/TeamcityLoggerTest.php b/tests/Output/Unit/Teamcity/TeamcityLoggerTest.php
index 0079237a..63b0fc07 100644
--- a/tests/Output/Unit/Teamcity/TeamcityLoggerTest.php
+++ b/tests/Output/Unit/Teamcity/TeamcityLoggerTest.php
@@ -89,8 +89,10 @@ public function handleSingleTestResultPublishesBenchMetricsAsMetadataBeforeTheTe
         $output = self::capture(static fn(TeamcityLogger $logger) => $logger->handleSingleTestResult($result));
 
         Assert::string($output)->contains('##teamcity[testMetadata');
-        Assert::string($output)->contains("name='bench.iterations'");
-        Assert::string($output)->contains("name='bench.shift.meanUs'");
+        Assert::string($output)->contains("name='bench.shift.Benchmark setup.iters'");
+        Assert::string($output)->contains("name='bench.shift.Time results.mean'");
+        // A time metric carries its dimension in `type`, where TeamCity charts it natively.
+        Assert::string($output)->contains("type='ms'");
 
         // testFinished closes the node the metadata attaches to, so every metadata line has to precede it.
         Assert::true(\strpos($output, 'testMetadata') < \strpos($output, 'testFinished'));
diff --git a/tests/Output/Unit/Teamcity/TeamcityMetricTypeTest.php b/tests/Output/Unit/Teamcity/TeamcityMetricTypeTest.php
new file mode 100644
index 00000000..0284b518
--- /dev/null
+++ b/tests/Output/Unit/Teamcity/TeamcityMetricTypeTest.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Output\Unit\Teamcity;
+
+use Testo\Assert;
+use Testo\Codecov\Covers;
+use Testo\Core\Metric\Memory;
+use Testo\Metric\Metric;
+use Testo\Core\Metric\Percent;
+use Testo\Core\Metric\Scalar;
+use Testo\Core\Metric\Time;
+use Testo\Output\Teamcity\Teamcity\TeamcityMetricType;
+use Testo\Test;
+
+#[Test]
+#[Covers(TeamcityMetricType::class)]
+final class TeamcityMetricTypeTest
+{
+    public function everyTimeUnitConvertsToMilliseconds(): void
+    {
+        // TeamCity charts time only in `ms`, so each time unit is scaled onto it at this boundary.
+        Assert::same(
+            TeamcityMetricType::convert(new Metric(2_000.0, Time::Nanoseconds)),
+            [TeamcityMetricType::Milliseconds, 2_000.0 / 1_000_000],
+        );
+        Assert::same(
+            TeamcityMetricType::convert(new Metric(5.0, Time::Microseconds)),
+            [TeamcityMetricType::Milliseconds, 5.0 / 1_000],
+        );
+        Assert::same(
+            TeamcityMetricType::convert(new Metric(42.0, Time::Milliseconds)),
+            [TeamcityMetricType::Milliseconds, 42.0],
+        );
+        Assert::same(
+            TeamcityMetricType::convert(new Metric(1.5, Time::Seconds)),
+            [TeamcityMetricType::Milliseconds, 1.5 * 1_000],
+        );
+    }
+
+    public function everyByteUnitConvertsToBytes(): void
+    {
+        Assert::same(
+            TeamcityMetricType::convert(new Metric(300, Memory::Bytes)),
+            [TeamcityMetricType::Bytes, 300],
+        );
+        Assert::same(
+            TeamcityMetricType::convert(new Metric(2, Memory::Kibibytes)),
+            [TeamcityMetricType::Bytes, 2048],
+        );
+        Assert::same(
+            TeamcityMetricType::convert(new Metric(3, Memory::Mebibytes)),
+            [TeamcityMetricType::Bytes, 3 * 1024 * 1024],
+        );
+    }
+
+    public function dimensionlessAndPercentPassThrough(): void
+    {
+        Assert::same(
+            TeamcityMetricType::convert(new Metric(97.3, Percent::Percent)),
+            [TeamcityMetricType::Percent, 97.3],
+        );
+        Assert::same(
+            TeamcityMetricType::convert(new Metric(20, Scalar::Number)),
+            [TeamcityMetricType::Number, 20],
+        );
+    }
+}
diff --git a/tests/Sandbox/Metadata/MetadataShowcaseTest.php b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
new file mode 100644
index 00000000..d939f46a
--- /dev/null
+++ b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
@@ -0,0 +1,163 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Sandbox\Metadata;
+
+use Testo\Assert;
+use Testo\Filter\Group;
+use Testo\Test;
+use Testo\Test\MetadataType;
+use Testo\Test\TestMetadata;
+
+/**
+ * Playground for the `testMetadata` TeamCity protocol.
+ *
+ * Every test declares one or more {@see TestMetadata} values that the test plugin's interceptor turns
+ * into `##teamcity[testMetadata …]` messages. Run the `sandbox` suite against an IDE or CI server that
+ * understands the protocol and watch each type render: numbers as charts and a table, text and links
+ * inline, images and artifacts as attachments, sourced from both local files and URLs.
+ *
+ * The leading `echo` in each test is deliberate: it makes the test emit output, which opens its
+ * `testStarted` node before the interceptor writes the metadata into it.
+ */
+#[Test]
+#[Group('sandbox', 'metadata')]
+final class MetadataShowcaseTest
+{
+    /**
+     * Several numeric keys — a CI server charts each across builds and lists them together as a table
+     * on the test's page.
+     */
+    #[TestMetadata(name: 'throughput (ops/s)', value: '1342', type: MetadataType::Number)]
+    #[TestMetadata(name: 'latency (ms)', value: '0.74', type: MetadataType::Number)]
+    #[TestMetadata(name: 'peak memory (MB)', value: '18.5', type: MetadataType::Number)]
+    #[TestMetadata(name: 'allocations', value: '20483', type: MetadataType::Number)]
+    public function numbers(): void
+    {
+        echo "Reporting a table of numeric metrics.\n";
+        Assert::true(true);
+    }
+
+    /**
+     * A single number is the simplest chartable metric.
+     */
+    #[TestMetadata(name: 'score', value: '97.3', type: MetadataType::Number)]
+    public function singleNumber(): void
+    {
+        echo "Reporting one number.\n";
+        Assert::true(true);
+    }
+
+    /**
+     * Dimensioned numbers — TeamCity formats the graph axis by the type, so the value carries no unit.
+     */
+    #[TestMetadata(name: 'duration', value: '434.5', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'peak memory', value: '1048576', type: MetadataType::Bytes)]
+    #[TestMetadata(name: 'coverage', value: '91.2', type: MetadataType::Percent)]
+    public function dimensionedNumbers(): void
+    {
+        echo "Reporting numbers with measurement dimensions.\n";
+        Assert::true(true);
+    }
+
+    /**
+     * A three-level table (`<prefix>.<row>.<column>`, no column group) whose every value shares one type
+     * — a grid a consumer can plot as a graph: rows are the x-axis (concurrency), columns are the series
+     * (backends), and the milliseconds are the y-axis.
+     */
+    #[TestMetadata(name: 'response time.redis.1', value: '0.4', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.postgres.1', value: '0.9', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.redis.2', value: '0.5', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.postgres.2', value: '1.1', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.redis.4', value: '0.7', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.postgres.4', value: '1.6', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.redis.8', value: '1.1', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.postgres.8', value: '2.7', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.redis.16', value: '2.0', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.postgres.16', value: '5.1', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.redis.32', value: '3.8', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.postgres.32', value: '9.4', type: MetadataType::Milliseconds)]
+    public function graphTable(): void
+    {
+        echo "Reporting a uniform three-level table to plot as a graph.\n";
+        Assert::true(true);
+    }
+
+    #[TestMetadata(name: 'summary', value: 'Processed 5 batches, 0 retries, warm cache.', type: MetadataType::Text)]
+    #[TestMetadata(name: 'commit', value: 'feature/sandbox-test-metadata @ 64f100e4', type: MetadataType::Text)]
+    public function text(): void
+    {
+        echo "Reporting free-form text metadata.\n";
+        Assert::true(true);
+    }
+
+    #[TestMetadata(name: 'build log', value: 'https://php-testo.github.io/', type: MetadataType::Link)]
+    #[TestMetadata(name: 'docs', value: 'https://php-testo.github.io/llms.txt', type: MetadataType::Link)]
+    public function links(): void
+    {
+        echo "Reporting clickable links.\n";
+        Assert::true(true);
+    }
+
+    /**
+     * An image referenced by URL — the value is emitted verbatim.
+     */
+    #[TestMetadata(
+        name: 'remote image',
+        value: 'https://github.com/php-testo/.github/blob/1.x/resources/logo-full.svg?raw=true',
+        type: MetadataType::Image,
+    )]
+    public function imageFromUrl(): void
+    {
+        echo "Reporting an image by URL.\n";
+        Assert::true(true);
+    }
+
+    /**
+     * An image shipped next to the test — the relative path resolves against this file's directory.
+     */
+    #[TestMetadata(name: 'local image', value: 'resources/chart.png', type: MetadataType::Image)]
+    public function imageFromLocalFile(): void
+    {
+        echo "Reporting an image from a local file.\n";
+        Assert::true(true);
+    }
+
+    /**
+     * A downloadable artifact from a local file — a CSV of raw measurements.
+     */
+    #[TestMetadata(name: 'measurements.csv', value: 'resources/report.csv', type: MetadataType::Artifact)]
+    public function artifactFromLocalFile(): void
+    {
+        echo "Reporting an artifact from a local file.\n";
+        Assert::true(true);
+    }
+
+    /**
+     * A downloadable artifact from a URL.
+     */
+    #[TestMetadata(
+        name: 'remote artifact',
+        value: 'https://php-testo.github.io/llms-full.txt',
+        type: MetadataType::Artifact,
+    )]
+    public function artifactFromUrl(): void
+    {
+        echo "Reporting an artifact by URL.\n";
+        Assert::true(true);
+    }
+
+    /**
+     * A single test can mix types: a headline number, a note, an image and its source link.
+     */
+    #[TestMetadata(name: 'coverage (%)', value: '86.4', type: MetadataType::Number)]
+    #[TestMetadata(name: 'note', value: 'Coverage rendered from the local chart below.', type: MetadataType::Text)]
+    #[TestMetadata(name: 'coverage chart', value: 'resources/chart.png', type: MetadataType::Image)]
+    #[TestMetadata(name: 'chart source', value: 'https://php-testo.github.io/', type: MetadataType::Link)]
+    public function mixedTypes(): void
+    {
+        echo "Reporting several metadata types from one test.\n";
+        Assert::true(true);
+    }
+}
diff --git a/tests/Sandbox/Metadata/resources/chart.png b/tests/Sandbox/Metadata/resources/chart.png
new file mode 100644
index 00000000..a2448c6b
Binary files /dev/null and b/tests/Sandbox/Metadata/resources/chart.png differ
diff --git a/tests/Sandbox/Metadata/resources/report.csv b/tests/Sandbox/Metadata/resources/report.csv
new file mode 100644
index 00000000..26e29c3a
--- /dev/null
+++ b/tests/Sandbox/Metadata/resources/report.csv
@@ -0,0 +1,6 @@
+iteration,throughput_ops,latency_ms
+1,1180,0.85
+2,1240,0.81
+3,1305,0.77
+4,1288,0.78
+5,1342,0.74
diff --git a/tests/Sandbox/Self/AssertTest.php b/tests/Sandbox/Self/AssertTest.php
index 60035583..c834f0ac 100644
--- a/tests/Sandbox/Self/AssertTest.php
+++ b/tests/Sandbox/Self/AssertTest.php
@@ -239,7 +239,7 @@ public function stream(): void
     {
         for ($i = 0; $i < 10; ++$i) {
             \usleep(100_000);
-            echo "Foo $i\n";
+            echo "Foo $i";
         }
 
         Assert::false(true);
@@ -258,13 +258,28 @@ public function logger(): void
     {
         echo "This test demonstrates logging to \e[32mmultiple channels\e[0m with different levels.\n";
 
-        $this->messenger->channel('query.sql')->debug(
+        $this->messenger->channel('query.sql/n')->debug(
             <<<SQL
                 SELECT *
                 FROM user
                 WHERE id = 42
                 SQL,
         );
+        $this->messenger->channel('query.sql/n')->debug(
+            <<<SQL
+                SELECT *
+                FROM user
+                WHERE id = 42
+                SQL,
+        );
+        $this->messenger->channel('query.sql/n')->debug(
+            <<<SQL
+                SELECT *
+                FROM user
+                WHERE id = %s
+                SQL,
+            context: ['42'],
+        );
 
         $this->messenger->channel('response.json')->write(
             <<<JSON