From 57e414a932a9a75501d020f2f0bcd81da6d01318 Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Wed, 26 Aug 2026 00:14:23 +0400
Subject: [PATCH 1/7] test(sandbox): showcase testMetadata reporting via a
 middleware plugin

Add a sandbox playground that emits ##teamcity[testMetadata] messages for
every TeamCity metadata type. A #[TestMetadata] attribute declares the values;
a TestMetadataInterceptor (registered by TestMetadataPlugin on the sandbox
suite) writes them straight to the stream after the test body runs, nested
between testStarted and testFinished like the built-in bench metrics.

Covers numbers (a chartable table), text, links, and images/artifacts sourced
from both local files and URLs; relative file references resolve against the
test directory.

Assisted-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 testo.php                                     |   2 +
 .../Sandbox/Metadata/MetadataShowcaseTest.php | 126 ++++++++++++++++++
 tests/Sandbox/Metadata/MetadataType.php       |  22 +++
 tests/Sandbox/Metadata/TestMetadata.php       |  23 ++++
 .../Metadata/TestMetadataInterceptor.php      |  87 ++++++++++++
 tests/Sandbox/Metadata/TestMetadataPlugin.php |  23 ++++
 tests/Sandbox/Metadata/resources/chart.png    | Bin 0 -> 722 bytes
 tests/Sandbox/Metadata/resources/report.csv   |   6 +
 8 files changed, 289 insertions(+)
 create mode 100644 tests/Sandbox/Metadata/MetadataShowcaseTest.php
 create mode 100644 tests/Sandbox/Metadata/MetadataType.php
 create mode 100644 tests/Sandbox/Metadata/TestMetadata.php
 create mode 100644 tests/Sandbox/Metadata/TestMetadataInterceptor.php
 create mode 100644 tests/Sandbox/Metadata/TestMetadataPlugin.php
 create mode 100644 tests/Sandbox/Metadata/resources/chart.png
 create mode 100644 tests/Sandbox/Metadata/resources/report.csv

diff --git a/testo.php b/testo.php
index e4ceb9eb..6226897f 100644
--- a/testo.php
+++ b/testo.php
@@ -6,6 +6,7 @@
 use Testo\Application\Config\FinderConfig;
 use Testo\Application\Config\SuiteConfig;
 use Testo\Testing\InjectPlugin;
+use Tests\Sandbox\Metadata\TestMetadataPlugin;
 
 return new ApplicationConfig(
     src: new FinderConfig(
@@ -48,6 +49,7 @@
                 location: new FinderConfig(
                     include: ['tests/Sandbox'],
                 ),
+                plugins: [new TestMetadataPlugin()],
             ),
         ],
         require 'internal/container/tests/suites.php',
diff --git a/tests/Sandbox/Metadata/MetadataShowcaseTest.php b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
new file mode 100644
index 00000000..42eec474
--- /dev/null
+++ b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
@@ -0,0 +1,126 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Sandbox\Metadata;
+
+use Testo\Assert;
+use Testo\Filter\Group;
+use Testo\Test;
+
+/**
+ * Playground for the `testMetadata` TeamCity protocol.
+ *
+ * Every test declares one or more {@see TestMetadata} values that {@see TestMetadataInterceptor} 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')]
+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);
+    }
+
+    #[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 chart',
+        value: 'https://raw.githubusercontent.com/php-testo/testo/1.x/resources/logo.png',
+        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 chart', 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/MetadataType.php b/tests/Sandbox/Metadata/MetadataType.php
new file mode 100644
index 00000000..4b9b99f1
--- /dev/null
+++ b/tests/Sandbox/Metadata/MetadataType.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Sandbox\Metadata;
+
+/**
+ * TeamCity `testMetadata` value types.
+ *
+ * The set a CI server and an IDE know how to render: a number it charts across builds, plain text, a
+ * clickable link, an inline image, and a downloadable artifact.
+ *
+ * @link https://www.jetbrains.com/help/teamcity/reporting-test-metadata.html
+ */
+enum MetadataType: string
+{
+    case Number = 'number';
+    case Text = 'text';
+    case Link = 'link';
+    case Image = 'image';
+    case Artifact = 'artifact';
+}
diff --git a/tests/Sandbox/Metadata/TestMetadata.php b/tests/Sandbox/Metadata/TestMetadata.php
new file mode 100644
index 00000000..3fe3f5ef
--- /dev/null
+++ b/tests/Sandbox/Metadata/TestMetadata.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Sandbox\Metadata;
+
+/**
+ * Attaches one `testMetadata` value to a test, emitted 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.
+ */
+#[\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/tests/Sandbox/Metadata/TestMetadataInterceptor.php b/tests/Sandbox/Metadata/TestMetadataInterceptor.php
new file mode 100644
index 00000000..eeb0115e
--- /dev/null
+++ b/tests/Sandbox/Metadata/TestMetadataInterceptor.php
@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Sandbox\Metadata;
+
+use Testo\Core\Context\TestInfo;
+use Testo\Core\Context\TestResult;
+use Testo\Core\Value\TestType;
+use Testo\Output\Teamcity\Teamcity\Formatter;
+use Testo\Pipeline\Attribute\InterceptorOptions;
+use Testo\Pipeline\Middleware\TestRunInterceptor;
+
+/**
+ * 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.
+ *
+ * @see Formatter::testMetadata()
+ */
+#[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;
+        $baseDir = \dirname($reflection->getFileName() ?: '.');
+
+        foreach ($reflection->getAttributes(TestMetadata::class) as $attribute) {
+            $meta = $attribute->newInstance();
+            $value = $this->resolveValue($meta, $baseDir);
+
+            $value === '' or \fwrite($this->output, Formatter::testMetadata(
+                testName: $info->name,
+                name: $meta->name,
+                value: $value,
+                type: $meta->type->value,
+                identity: $info->identity,
+            ) . "\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),
+        };
+    }
+
+    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/tests/Sandbox/Metadata/TestMetadataPlugin.php b/tests/Sandbox/Metadata/TestMetadataPlugin.php
new file mode 100644
index 00000000..278b30f7
--- /dev/null
+++ b/tests/Sandbox/Metadata/TestMetadataPlugin.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Sandbox\Metadata;
+
+use Internal\Container\Container;
+use Testo\Common\PluginConfigurator;
+use Testo\Pipeline\InterceptorCollector;
+
+/**
+ * Wires {@see TestMetadataInterceptor} into a suite so any test carrying {@see TestMetadata} reports
+ * its values to TeamCity. A sandbox playground for exercising the `testMetadata` protocol across every
+ * value type — numbers, text, links, images and artifacts, referenced both as local files and URLs.
+ */
+final class TestMetadataPlugin implements PluginConfigurator
+{
+    #[\Override]
+    public function configure(Container $container): void
+    {
+        $container->get(InterceptorCollector::class)->addInterceptor(new TestMetadataInterceptor());
+    }
+}
diff --git a/tests/Sandbox/Metadata/resources/chart.png b/tests/Sandbox/Metadata/resources/chart.png
new file mode 100644
index 0000000000000000000000000000000000000000..a2448c6b9cb5ce40cdcb7355545c246a1f660fee
GIT binary patch
literal 722
zcmeAS@N?(olHy`uVBq!ia0vp^AAq=mg9%7FUwKggq&N#aB8wRq_>O=u<5X=vX$A(S
z7Ec$)kcv5PZ#V`$3J`G!eDliHqCiKwh;grp*ahiVcfT}fE%Eupnc=vj^qj}Vnz$3D
zbrqGh)%P8bu6O5Wu=l*MgkzS7<7B0bAQs=Q1)hQ?noVl110s0py*vMg+i%P2|NWa?
z`{%>P{hw8Cm(<kmk;=|ddU1K_ubbN2C-S|sJm%*2voXig<K_|BUyDB5p8WYXeOI{U
zzb}72-kg2yQd2V{pZxF3L6=R_#rI_OEM;B(_^jO5xzDvKfu64a!ZV*O{L!CHzWe9d
z*1Y`xzGC9Xgw4M3rdMZWE|1q=TYp${z5VO-EnjtyPoG{_Wo}je<Hmab;<HWmb`NJ|
z0u8LVl6(H@=bGrg$&Yi3l>d9?|Cqev?fMt<+-(;>=cv-W{PNk89XI!$4p{7|C-wf&
z_JS*uZ~dB<{7v@!$J;O8RzCQ0I$rG0zq}%YhY39|AA582ohz*Ql|66ubIyAr@6@g*
zd`oW8x1aUz&{2NXYdqV&I3BNfUi{H`!ojA^`3}?jcD>!{wN2Ed=JK`eG6kZ8BFZ2M
b=09UfjOoqZ8<(qriIl<9)z4*}Q$iB}<=Q&$

literal 0
HcmV?d00001

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

From 6f541817c4e390d2e356e56d48190eeb1ed63bb8 Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Wed, 26 Aug 2026 10:03:20 +0400
Subject: [PATCH 2/7] feat(bench): report metrics as a grouped, dimensioned
 metadata table
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bench metrics now spell `bench.<case>.<columnGroup>.<column>` instead of the
flat `bench.<case>.<metric>`, so a consumer that understands the four-segment
`testMetadata` convention rebuilds them as a sortable table with spanning
column-group bands — the same grouping the terminal's ASCII table prints:
Benchmark setup, Time results, Filtered results, Summary. Every case emits every
column so the grid stays rectangular, and the standalone `bench.iterations`
counter folds into each row's Benchmark setup group to keep the key depth
uniform — a mixed depth would drop a consumer back to a flat list.

The unit no longer hides in the leaf name. A value is a `Testo\Core\Metric\Metric`
— a generic `Metric<TUnit>` carrying its number in the unit it was measured in.
Units are split into family enums (Time, Memory, Percent, Scalar) under a shared
`Unit` interface, so a `Metric<Percent>` cannot be handed to a consumer keyed to
`Metric<Time>`. Each reporter renders the unit its own way: JUnit — no type
attribute — suffixes the flat property name with the native unit (`…mean.us`,
`…memory.bytes`); TeamCity converts at its boundary via `TeamcityMetricType` to
the four number types it charts, scaling every time unit to milliseconds and
every byte unit to bytes. The source keeps native precision for every consumer
instead of rounding once at the mapper.

Affects the TeamCity `testMetadata` and JUnit `<property>` output; the HTML/JSON
structured map is unchanged. The sandbox metadata playground gains ms/bytes/
percent examples.

Assisted-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 core/Core/Metric/Memory.php                   | 24 +++++++
 core/Core/Metric/Metric.php                   | 27 +++++++
 core/Core/Metric/Percent.php                  | 21 ++++++
 core/Core/Metric/Scalar.php                   | 22 ++++++
 core/Core/Metric/Time.php                     | 24 +++++++
 core/Core/Metric/Unit.php                     | 25 +++++++
 core/Output/JUnit/Internal/JUnitCaseNode.php  |  4 +-
 core/Output/JUnit/Internal/JUnitWriter.php    |  8 ++-
 core/Output/Rendering/BenchMapper.php         | 72 +++++++++++++------
 core/Output/Teamcity/Teamcity/Formatter.php   |  4 +-
 .../Teamcity/Teamcity/TeamcityLogger.php      |  5 +-
 .../Teamcity/Teamcity/TeamcityMetricType.php  | 72 +++++++++++++++++++
 tests/Output/Unit/JUnit/JUnitWriterTest.php   |  8 ++-
 .../Output/Unit/Rendering/BenchMapperTest.php | 51 ++++++++-----
 .../Unit/Teamcity/TeamcityLoggerTest.php      |  6 +-
 .../Unit/Teamcity/TeamcityMetricTypeTest.php  | 51 +++++++++++++
 .../Sandbox/Metadata/MetadataShowcaseTest.php | 12 ++++
 tests/Sandbox/Metadata/MetadataType.php       |  8 ++-
 18 files changed, 390 insertions(+), 54 deletions(-)
 create mode 100644 core/Core/Metric/Memory.php
 create mode 100644 core/Core/Metric/Metric.php
 create mode 100644 core/Core/Metric/Percent.php
 create mode 100644 core/Core/Metric/Scalar.php
 create mode 100644 core/Core/Metric/Time.php
 create mode 100644 core/Core/Metric/Unit.php
 create mode 100644 core/Output/Teamcity/Teamcity/TeamcityMetricType.php
 create mode 100644 tests/Output/Unit/Teamcity/TeamcityMetricTypeTest.php

diff --git a/core/Core/Metric/Memory.php b/core/Core/Metric/Memory.php
new file mode 100644
index 00000000..cfacd7e6
--- /dev/null
+++ b/core/Core/Metric/Memory.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+/**
+ * An amount of memory, in one of the units it may be measured in.
+ *
+ * @api
+ */
+enum Memory: string implements Unit
+{
+    case Bytes = 'bytes';
+    case Kilobytes = 'kb';
+    case Megabytes = 'mb';
+    case Gigabytes = 'gb';
+
+    #[\Override]
+    public function suffix(): string
+    {
+        return '.' . $this->value;
+    }
+}
diff --git a/core/Core/Metric/Metric.php b/core/Core/Metric/Metric.php
new file mode 100644
index 00000000..51a1f304
--- /dev/null
+++ b/core/Core/Metric/Metric.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+/**
+ * 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,
+    ) {}
+}
diff --git a/core/Core/Metric/Percent.php b/core/Core/Metric/Percent.php
new file mode 100644
index 00000000..9823c3a6
--- /dev/null
+++ b/core/Core/Metric/Percent.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+/**
+ * A ratio already expressed out of 100.
+ *
+ * @api
+ */
+enum Percent: string implements Unit
+{
+    case Percent = 'percent';
+
+    #[\Override]
+    public function suffix(): string
+    {
+        return '.' . $this->value;
+    }
+}
diff --git a/core/Core/Metric/Scalar.php b/core/Core/Metric/Scalar.php
new file mode 100644
index 00000000..f899681b
--- /dev/null
+++ b/core/Core/Metric/Scalar.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+/**
+ * A dimensionless quantity — a count of iterations or calls, a rank.
+ *
+ * @api
+ */
+enum Scalar: string implements Unit
+{
+    case Number = 'number';
+
+    #[\Override]
+    public function suffix(): string
+    {
+        // A bare count needs no unit to stay legible in a flat namespace.
+        return '';
+    }
+}
diff --git a/core/Core/Metric/Time.php b/core/Core/Metric/Time.php
new file mode 100644
index 00000000..d0921e92
--- /dev/null
+++ b/core/Core/Metric/Time.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+/**
+ * A duration, in one of the units it may be measured in.
+ *
+ * @api
+ */
+enum Time: string implements Unit
+{
+    case Nanoseconds = 'ns';
+    case Microseconds = 'us';
+    case Milliseconds = 'ms';
+    case Seconds = 's';
+
+    #[\Override]
+    public function suffix(): string
+    {
+        return '.' . $this->value;
+    }
+}
diff --git a/core/Core/Metric/Unit.php b/core/Core/Metric/Unit.php
new file mode 100644
index 00000000..63d2dae2
--- /dev/null
+++ b/core/Core/Metric/Unit.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Metric;
+
+/**
+ * The unit a {@see Metric} was measured in.
+ *
+ * The parent of every dimension enum ({@see Time}, {@see Memory}, {@see Percent}, {@see 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 its own enum, and its cases scale within it; converting between families is a reporter's
+ * job at its own boundary.
+ *
+ * @api
+ */
+interface Unit
+{
+    /**
+     * Suffix a flat-namespace consumer appends to a metric name so the unit survives where there is no
+     * field to carry it — a JUnit `<property>` name becomes `…mean.us`, `…memory.bytes`. A dimensionless
+     * number adds nothing.
+     */
+    public function suffix(): string;
+}
diff --git a/core/Output/JUnit/Internal/JUnitCaseNode.php b/core/Output/JUnit/Internal/JUnitCaseNode.php
index 4a9a984c..7d89852d 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\Core\Metric\Metric;
+use Testo\Core\Metric\Unit;
 
 /**
  * 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..3bc6bbba 100644
--- a/core/Output/JUnit/Internal/JUnitWriter.php
+++ b/core/Output/JUnit/Internal/JUnitWriter.php
@@ -452,10 +452,12 @@ 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 to
+                // survive the flat namespace: `…mean.ms`, `…memory.bytes`.
+                $xml->writeAttribute('name', $name . $metric->unit->suffix());
+                $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..a0507384 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\Core\Metric\Metric;
+use Testo\Core\Metric\Percent;
+use Testo\Core\Metric\Scalar;
+use Testo\Core\Metric\Time;
+use Testo\Core\Metric\Unit;
 
 /**
  * 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..62fea0b2
--- /dev/null
+++ b/core/Output/Teamcity/Teamcity/TeamcityMetricType.php
@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Output\Teamcity\Teamcity;
+
+use Testo\Core\Metric\Memory;
+use Testo\Core\Metric\Metric;
+use Testo\Core\Metric\Percent;
+use Testo\Core\Metric\Scalar;
+use Testo\Core\Metric\Time;
+use Testo\Core\Metric\Unit;
+
+/**
+ * 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;
+        $value = $metric->value;
+
+        return match (true) {
+            $unit instanceof Time => [self::Milliseconds, self::timeToMs($unit, $value)],
+            $unit instanceof Memory => [self::Bytes, self::memoryToBytes($unit, $value)],
+            $unit instanceof Percent => [self::Percent, $value],
+            $unit instanceof Scalar => [self::Number, $value],
+            default => [self::Number, $value],
+        };
+    }
+
+    private static function timeToMs(Time $unit, int|float $value): int|float
+    {
+        return match ($unit) {
+            Time::Nanoseconds => $value / 1_000_000,
+            Time::Microseconds => $value / 1_000,
+            Time::Milliseconds => $value,
+            Time::Seconds => $value * 1_000,
+        };
+    }
+
+    private static function memoryToBytes(Memory $unit, int|float $value): int|float
+    {
+        return match ($unit) {
+            Memory::Bytes => $value,
+            Memory::Kilobytes => $value * 1024,
+            Memory::Megabytes => $value * 1024 * 1024,
+            Memory::Gigabytes => $value * 1024 * 1024 * 1024,
+        };
+    }
+}
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..7d85a284
--- /dev/null
+++ b/tests/Output/Unit/Teamcity/TeamcityMetricTypeTest.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Output\Unit\Teamcity;
+
+use Testo\Assert;
+use Testo\Codecov\Covers;
+use Testo\Core\Metric\Memory;
+use Testo\Core\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.1, Time::Microseconds)),
+            [TeamcityMetricType::Milliseconds, 5.1 / 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::Kilobytes)),
+            [TeamcityMetricType::Bytes, 2048]);
+        Assert::same(TeamcityMetricType::convert(new Metric(3, Memory::Megabytes)),
+            [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
index 42eec474..3cee955a 100644
--- a/tests/Sandbox/Metadata/MetadataShowcaseTest.php
+++ b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
@@ -47,6 +47,18 @@ public function singleNumber(): void
         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);
+    }
+
     #[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
diff --git a/tests/Sandbox/Metadata/MetadataType.php b/tests/Sandbox/Metadata/MetadataType.php
index 4b9b99f1..d8bd95b4 100644
--- a/tests/Sandbox/Metadata/MetadataType.php
+++ b/tests/Sandbox/Metadata/MetadataType.php
@@ -7,14 +7,18 @@
 /**
  * TeamCity `testMetadata` value types.
  *
- * The set a CI server and an IDE know how to render: a number it charts across builds, plain text, a
- * clickable link, an inline image, and a downloadable artifact.
+ * 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
  */
 enum MetadataType: string
 {
     case Number = 'number';
+    case Milliseconds = 'ms';
+    case Bytes = 'bytes';
+    case Percent = 'percent';
     case Text = 'text';
     case Link = 'link';
     case Image = 'image';

From 32d41526089a2fb0bee05a56ec8ed431206545b4 Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Wed, 26 Aug 2026 10:10:04 +0400
Subject: [PATCH 3/7] test(sandbox): add a graph-plottable metadata table

A three-level `<prefix>.<row>.<column>` table (no column group) whose values all
share one type, so the metadata consumer can plot it as a graph rather than a
grid: rows as the x-axis, columns as the series, milliseconds as the y-axis.

Assisted-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../Sandbox/Metadata/MetadataShowcaseTest.php | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/tests/Sandbox/Metadata/MetadataShowcaseTest.php b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
index 3cee955a..fb4e99f7 100644
--- a/tests/Sandbox/Metadata/MetadataShowcaseTest.php
+++ b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
@@ -59,6 +59,29 @@ public function dimensionedNumbers(): void
         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.1.redis', value: '0.4', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.1.postgres', value: '0.9', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.2.redis', value: '0.5', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.2.postgres', value: '1.1', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.4.redis', value: '0.7', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.4.postgres', value: '1.6', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.8.redis', value: '1.1', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.8.postgres', value: '2.7', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.16.redis', value: '2.0', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.16.postgres', value: '5.1', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.32.redis', value: '3.8', type: MetadataType::Milliseconds)]
+    #[TestMetadata(name: 'response time.32.postgres', 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

From d1db5643648e019bd32cf2ce4ee0edc8b3688ba0 Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Wed, 26 Aug 2026 10:20:46 +0400
Subject: [PATCH 4/7] refactor(test): move the TestMetadata attribute into the
 test plugin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `#[TestMetadata]` attribute and its interceptor move out of the sandbox and
into `testo/test`, so any suite can attach `testMetadata` to a test — the
interceptor is registered by the default TestPlugin, and the attribute lives
beside `#[Test]` as `Testo\Test\TestMetadata`.

The interceptor builds the `##teamcity[testMetadata …]` service message itself
rather than through the core formatter, so the plugin depends on nothing
internal; the format is TeamCity's own stable protocol. The sandbox keeps only
the showcase test, now importing the attribute from the plugin, and its bespoke
plugin/interceptor are gone.

Assisted-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/Internal}/TestMetadataInterceptor.php | 65 ++++++++++---
 .../test/src}/MetadataType.php                |  3 +-
 plugin/test/src/TestMetadata.php              | 27 ++++++
 plugin/test/src/TestPlugin.php                |  7 +-
 .../Unit/Fixture/TestClassWithMetadata.php    | 21 ++++
 .../Internal/TestMetadataInterceptorTest.php  | 97 +++++++++++++++++++
 testo.php                                     |  2 -
 .../Sandbox/Metadata/MetadataShowcaseTest.php | 28 +++---
 tests/Sandbox/Metadata/TestMetadata.php       | 23 -----
 tests/Sandbox/Metadata/TestMetadataPlugin.php | 23 -----
 10 files changed, 218 insertions(+), 78 deletions(-)
 rename {tests/Sandbox/Metadata => plugin/test/src/Internal}/TestMetadataInterceptor.php (56%)
 rename {tests/Sandbox/Metadata => plugin/test/src}/MetadataType.php (95%)
 create mode 100644 plugin/test/src/TestMetadata.php
 create mode 100644 plugin/test/tests/Unit/Fixture/TestClassWithMetadata.php
 create mode 100644 plugin/test/tests/Unit/Internal/TestMetadataInterceptorTest.php
 delete mode 100644 tests/Sandbox/Metadata/TestMetadata.php
 delete mode 100644 tests/Sandbox/Metadata/TestMetadataPlugin.php

diff --git a/tests/Sandbox/Metadata/TestMetadataInterceptor.php b/plugin/test/src/Internal/TestMetadataInterceptor.php
similarity index 56%
rename from tests/Sandbox/Metadata/TestMetadataInterceptor.php
rename to plugin/test/src/Internal/TestMetadataInterceptor.php
index eeb0115e..4cc63878 100644
--- a/tests/Sandbox/Metadata/TestMetadataInterceptor.php
+++ b/plugin/test/src/Internal/TestMetadataInterceptor.php
@@ -2,25 +2,27 @@
 
 declare(strict_types=1);
 
-namespace Tests\Sandbox\Metadata;
+namespace Testo\Test\Internal;
 
 use Testo\Core\Context\TestInfo;
 use Testo\Core\Context\TestResult;
 use Testo\Core\Value\TestType;
-use Testo\Output\Teamcity\Teamcity\Formatter;
 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.
+ * `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.
  *
- * @see Formatter::testMetadata()
+ * @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
@@ -43,19 +45,26 @@ public function runTest(TestInfo $info, callable $next): TestResult
     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 ($reflection->getAttributes(TestMetadata::class) as $attribute) {
+        foreach ($attributes as $attribute) {
             $meta = $attribute->newInstance();
             $value = $this->resolveValue($meta, $baseDir);
 
-            $value === '' or \fwrite($this->output, Formatter::testMetadata(
-                testName: $info->name,
-                name: $meta->name,
-                value: $value,
-                type: $meta->type->value,
-                identity: $info->identity,
-            ) . "\n");
+            $value === '' or \fwrite($this->output, $this->format([
+                'testName' => $info->name,
+                'name' => $meta->name,
+                'type' => $meta->type->value,
+                'value' => $value,
+                'flowId' => $flowId,
+            ]) . "\n");
         }
     }
 
@@ -75,6 +84,34 @@ private function resolveValue(TestMetadata $meta, string $baseDir): string
         };
     }
 
+    /**
+     * 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;
diff --git a/tests/Sandbox/Metadata/MetadataType.php b/plugin/test/src/MetadataType.php
similarity index 95%
rename from tests/Sandbox/Metadata/MetadataType.php
rename to plugin/test/src/MetadataType.php
index d8bd95b4..9d008040 100644
--- a/tests/Sandbox/Metadata/MetadataType.php
+++ b/plugin/test/src/MetadataType.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Tests\Sandbox\Metadata;
+namespace Testo\Test;
 
 /**
  * TeamCity `testMetadata` value types.
@@ -12,6 +12,7 @@
  * 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
 {
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 6226897f..e4ceb9eb 100644
--- a/testo.php
+++ b/testo.php
@@ -6,7 +6,6 @@
 use Testo\Application\Config\FinderConfig;
 use Testo\Application\Config\SuiteConfig;
 use Testo\Testing\InjectPlugin;
-use Tests\Sandbox\Metadata\TestMetadataPlugin;
 
 return new ApplicationConfig(
     src: new FinderConfig(
@@ -49,7 +48,6 @@
                 location: new FinderConfig(
                     include: ['tests/Sandbox'],
                 ),
-                plugins: [new TestMetadataPlugin()],
             ),
         ],
         require 'internal/container/tests/suites.php',
diff --git a/tests/Sandbox/Metadata/MetadataShowcaseTest.php b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
index fb4e99f7..f647f2b3 100644
--- a/tests/Sandbox/Metadata/MetadataShowcaseTest.php
+++ b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
@@ -7,11 +7,13 @@
 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 {@see TestMetadataInterceptor} turns
+ * 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.
@@ -64,18 +66,18 @@ public function dimensionedNumbers(): void
      * — 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.1.redis', value: '0.4', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.1.postgres', value: '0.9', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.2.redis', value: '0.5', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.2.postgres', value: '1.1', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.4.redis', value: '0.7', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.4.postgres', value: '1.6', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.8.redis', value: '1.1', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.8.postgres', value: '2.7', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.16.redis', value: '2.0', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.16.postgres', value: '5.1', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.32.redis', value: '3.8', type: MetadataType::Milliseconds)]
-    #[TestMetadata(name: 'response time.32.postgres', value: '9.4', type: MetadataType::Milliseconds)]
+    #[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";
diff --git a/tests/Sandbox/Metadata/TestMetadata.php b/tests/Sandbox/Metadata/TestMetadata.php
deleted file mode 100644
index 3fe3f5ef..00000000
--- a/tests/Sandbox/Metadata/TestMetadata.php
+++ /dev/null
@@ -1,23 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Tests\Sandbox\Metadata;
-
-/**
- * Attaches one `testMetadata` value to a test, emitted 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.
- */
-#[\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/tests/Sandbox/Metadata/TestMetadataPlugin.php b/tests/Sandbox/Metadata/TestMetadataPlugin.php
deleted file mode 100644
index 278b30f7..00000000
--- a/tests/Sandbox/Metadata/TestMetadataPlugin.php
+++ /dev/null
@@ -1,23 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Tests\Sandbox\Metadata;
-
-use Internal\Container\Container;
-use Testo\Common\PluginConfigurator;
-use Testo\Pipeline\InterceptorCollector;
-
-/**
- * Wires {@see TestMetadataInterceptor} into a suite so any test carrying {@see TestMetadata} reports
- * its values to TeamCity. A sandbox playground for exercising the `testMetadata` protocol across every
- * value type — numbers, text, links, images and artifacts, referenced both as local files and URLs.
- */
-final class TestMetadataPlugin implements PluginConfigurator
-{
-    #[\Override]
-    public function configure(Container $container): void
-    {
-        $container->get(InterceptorCollector::class)->addInterceptor(new TestMetadataInterceptor());
-    }
-}

From 7faa99097a7e1841ac8ff93aa6f1bb1be80b9800 Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Wed, 26 Aug 2026 20:12:34 +0400
Subject: [PATCH 5/7] test(sandbox): tag metadata tests and tweak the metadata
 playground

Add a `metadata` group to the bench self-test and the sandbox showcase so the
metadata-reporting tests can be run as a set, rename the showcase's image
entries, point the remote-image example at a reachable asset, and extend the
Assert sandbox's logging demo.

Assisted-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 plugin/bench/tests/Self/BenchAttr.php         |  2 +-
 .../Sandbox/Metadata/MetadataShowcaseTest.php |  8 ++++----
 tests/Sandbox/Self/AssertTest.php             | 19 +++++++++++++++++--
 3 files changed, 22 insertions(+), 7 deletions(-)

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/tests/Sandbox/Metadata/MetadataShowcaseTest.php b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
index f647f2b3..d939f46a 100644
--- a/tests/Sandbox/Metadata/MetadataShowcaseTest.php
+++ b/tests/Sandbox/Metadata/MetadataShowcaseTest.php
@@ -22,7 +22,7 @@
  * `testStarted` node before the interceptor writes the metadata into it.
  */
 #[Test]
-#[Group('sandbox')]
+#[Group('sandbox', 'metadata')]
 final class MetadataShowcaseTest
 {
     /**
@@ -104,8 +104,8 @@ public function links(): void
      * An image referenced by URL — the value is emitted verbatim.
      */
     #[TestMetadata(
-        name: 'remote chart',
-        value: 'https://raw.githubusercontent.com/php-testo/testo/1.x/resources/logo.png',
+        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
@@ -117,7 +117,7 @@ public function imageFromUrl(): void
     /**
      * An image shipped next to the test — the relative path resolves against this file's directory.
      */
-    #[TestMetadata(name: 'local chart', value: 'resources/chart.png', type: MetadataType::Image)]
+    #[TestMetadata(name: 'local image', value: 'resources/chart.png', type: MetadataType::Image)]
     public function imageFromLocalFile(): void
     {
         echo "Reporting an image from a local file.\n";
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

From 3bc251c58673a2edaab45f94a7bb902789605319 Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Fri, 4 Sep 2026 00:44:21 +0400
Subject: [PATCH 6/7] feat(core): fetch attributes of every enum case through
 Reflection

Every case is present in the result, in declaration order, so a caller can walk an enum once and fall back to a default where a case carries nothing.

Assisted-By: Claude Fable 5.1
---
 core/Common/Reflection.php                | 31 +++++++++++++++++++++++
 tests/Common/Stub/CaseMarkerAttribute.php | 13 ++++++++++
 tests/Common/Stub/MarkedEnum.php          | 16 ++++++++++++
 tests/Common/Unit/ReflectionTest.php      | 30 ++++++++++++++++++++++
 4 files changed, 90 insertions(+)
 create mode 100644 tests/Common/Stub/CaseMarkerAttribute.php
 create mode 100644 tests/Common/Stub/MarkedEnum.php

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/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]);
+    }
 }

From 65884cce876fcb33a80ea03988a245f546fa8dcb Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Fri, 4 Sep 2026 00:44:33 +0400
Subject: [PATCH 7/7] feat(metric): declare unit families with attributes and
 convert between units

refactor(output): build the JUnit property suffix in the writer instead of on the unit

The metric engine moves to `Testo\Metric`: `#[Dimension]` names what an enum measures, `#[Factor]` on a case gives its multiplier to the family's base unit, and `Units` reflects both once per enum and does the arithmetic. `Testo\Core\Metric` keeps only the concrete families. A conversion stays integral while every operand is an integer, so `2 KiB` is `2048` bytes rather than `2048.0`. `compact()` derives the most readable unit from the factors alone, so no per-family hook is needed.

`Memory` is renamed to its binary units (`KiB`, `MiB`, `GiB`): the factors were already 1024-based, and the SI names misrepresented them. Backing values are the unit symbols, which the JUnit writer now appends itself; the `suffix()` method was a single reporter's concern living in the core contract.

Assisted-By: Claude Fable 5.1
---
 core/Core/Metric/Memory.php                   |  32 ++--
 core/Core/Metric/Percent.php                  |  12 +-
 core/Core/Metric/Scalar.php                   |  13 +-
 core/Core/Metric/Time.php                     |  21 ++-
 core/Core/Metric/Unit.php                     |  25 ---
 core/Metric/Dimension.php                     |  25 +++
 core/Metric/Exception/IncompatibleUnits.php   |  26 +++
 .../Exception/InvalidUnitDeclaration.php      |  30 ++++
 core/Metric/Factor.php                        |  26 +++
 core/{Core => }/Metric/Metric.php             |  27 +++-
 core/Metric/Unit.php                          |  33 ++++
 core/Metric/UnitConversion.php                |  25 +++
 core/Metric/UnitFamily.php                    |  58 +++++++
 core/Metric/Units.php                         | 122 ++++++++++++++
 core/Output/JUnit/Internal/JUnitCaseNode.php  |   4 +-
 core/Output/JUnit/Internal/JUnitWriter.php    |   8 +-
 core/Output/Rendering/BenchMapper.php         |   4 +-
 .../Teamcity/Teamcity/TeamcityMetricType.php  |  35 +---
 testo.php                                     |   1 +
 tests/Core/Metric/BuiltinUnitsTest.php        |  53 ++++++
 tests/Core/suites.php                         |   6 +
 tests/Metric/Fixture/Distance.php             |  27 ++++
 tests/Metric/Fixture/NegativeFactor.php       |  18 +++
 tests/Metric/Fixture/NotAUnit.php             |  13 ++
 tests/Metric/Fixture/Plain.php                |  18 +++
 tests/Metric/MetricTest.php                   |  42 +++++
 tests/Metric/UnitsTest.php                    | 152 ++++++++++++++++++
 tests/Metric/suites.php                       |  19 +++
 .../Unit/Teamcity/TeamcityMetricTypeTest.php  |  56 ++++---
 29 files changed, 821 insertions(+), 110 deletions(-)
 delete mode 100644 core/Core/Metric/Unit.php
 create mode 100644 core/Metric/Dimension.php
 create mode 100644 core/Metric/Exception/IncompatibleUnits.php
 create mode 100644 core/Metric/Exception/InvalidUnitDeclaration.php
 create mode 100644 core/Metric/Factor.php
 rename core/{Core => }/Metric/Metric.php (50%)
 create mode 100644 core/Metric/Unit.php
 create mode 100644 core/Metric/UnitConversion.php
 create mode 100644 core/Metric/UnitFamily.php
 create mode 100644 core/Metric/Units.php
 create mode 100644 tests/Core/Metric/BuiltinUnitsTest.php
 create mode 100644 tests/Metric/Fixture/Distance.php
 create mode 100644 tests/Metric/Fixture/NegativeFactor.php
 create mode 100644 tests/Metric/Fixture/NotAUnit.php
 create mode 100644 tests/Metric/Fixture/Plain.php
 create mode 100644 tests/Metric/MetricTest.php
 create mode 100644 tests/Metric/UnitsTest.php
 create mode 100644 tests/Metric/suites.php

diff --git a/core/Core/Metric/Memory.php b/core/Core/Metric/Memory.php
index cfacd7e6..1f58cb00 100644
--- a/core/Core/Metric/Memory.php
+++ b/core/Core/Metric/Memory.php
@@ -4,21 +4,31 @@
 
 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 one of the units it may be measured in.
+ * 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
 {
-    case Bytes = 'bytes';
-    case Kilobytes = 'kb';
-    case Megabytes = 'mb';
-    case Gigabytes = 'gb';
-
-    #[\Override]
-    public function suffix(): string
-    {
-        return '.' . $this->value;
-    }
+    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
index 9823c3a6..6e2b16a6 100644
--- a/core/Core/Metric/Percent.php
+++ b/core/Core/Metric/Percent.php
@@ -4,18 +4,18 @@
 
 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';
-
-    #[\Override]
-    public function suffix(): string
-    {
-        return '.' . $this->value;
-    }
 }
diff --git a/core/Core/Metric/Scalar.php b/core/Core/Metric/Scalar.php
index f899681b..61587c11 100644
--- a/core/Core/Metric/Scalar.php
+++ b/core/Core/Metric/Scalar.php
@@ -4,19 +4,18 @@
 
 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';
-
-    #[\Override]
-    public function suffix(): string
-    {
-        // A bare count needs no unit to stay legible in a flat namespace.
-        return '';
-    }
 }
diff --git a/core/Core/Metric/Time.php b/core/Core/Metric/Time.php
index d0921e92..5f4c88b7 100644
--- a/core/Core/Metric/Time.php
+++ b/core/Core/Metric/Time.php
@@ -4,21 +4,30 @@
 
 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';
-    case Seconds = 's';
 
-    #[\Override]
-    public function suffix(): string
-    {
-        return '.' . $this->value;
-    }
+    #[Factor(1_000_000_000)]
+    case Seconds = 's';
 }
diff --git a/core/Core/Metric/Unit.php b/core/Core/Metric/Unit.php
deleted file mode 100644
index 63d2dae2..00000000
--- a/core/Core/Metric/Unit.php
+++ /dev/null
@@ -1,25 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Testo\Core\Metric;
-
-/**
- * The unit a {@see Metric} was measured in.
- *
- * The parent of every dimension enum ({@see Time}, {@see Memory}, {@see Percent}, {@see 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 its own enum, and its cases scale within it; converting between families is a reporter's
- * job at its own boundary.
- *
- * @api
- */
-interface Unit
-{
-    /**
-     * Suffix a flat-namespace consumer appends to a metric name so the unit survives where there is no
-     * field to carry it — a JUnit `<property>` name becomes `…mean.us`, `…memory.bytes`. A dimensionless
-     * number adds nothing.
-     */
-    public function suffix(): string;
-}
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/Core/Metric/Metric.php b/core/Metric/Metric.php
similarity index 50%
rename from core/Core/Metric/Metric.php
rename to core/Metric/Metric.php
index 51a1f304..3aa17172 100644
--- a/core/Core/Metric/Metric.php
+++ b/core/Metric/Metric.php
@@ -2,7 +2,9 @@
 
 declare(strict_types=1);
 
-namespace Testo\Core\Metric;
+namespace Testo\Metric;
+
+use Testo\Metric\Exception\IncompatibleUnits;
 
 /**
  * One number a test produced, together with the unit it was measured in.
@@ -24,4 +26,27 @@ 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 7d89852d..88fe8ebf 100644
--- a/core/Output/JUnit/Internal/JUnitCaseNode.php
+++ b/core/Output/JUnit/Internal/JUnitCaseNode.php
@@ -5,8 +5,8 @@
 namespace Testo\Output\JUnit\Internal;
 
 use Testo\Core\Value\Status;
-use Testo\Core\Metric\Metric;
-use Testo\Core\Metric\Unit;
+use Testo\Metric\Unit;
+use Testo\Metric\Metric;
 
 /**
  * Captured `<testcase>` payload produced from a single `TestResult`.
diff --git a/core/Output/JUnit/Internal/JUnitWriter.php b/core/Output/JUnit/Internal/JUnitWriter.php
index 3bc6bbba..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;
@@ -454,9 +455,10 @@ private function writeCase(\XMLWriter $xml, JUnitCaseNode $case): void
             $xml->startElement('properties');
             foreach ($case->properties as $name => $metric) {
                 $xml->startElement('property');
-                // A `<property>` carries no dimension of its own, so the unit rides on the name to
-                // survive the flat namespace: `…mean.ms`, `…memory.bytes`.
-                $xml->writeAttribute('name', $name . $metric->unit->suffix());
+                // 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();
             }
diff --git a/core/Output/Rendering/BenchMapper.php b/core/Output/Rendering/BenchMapper.php
index a0507384..7e922ab0 100644
--- a/core/Output/Rendering/BenchMapper.php
+++ b/core/Output/Rendering/BenchMapper.php
@@ -11,11 +11,11 @@
 use Testo\Bench\Dto\Report\Severity;
 use Testo\Bench\Dto\Snap;
 use Testo\Core\Metric\Memory;
-use Testo\Core\Metric\Metric;
+use Testo\Metric\Unit;
+use Testo\Metric\Metric;
 use Testo\Core\Metric\Percent;
 use Testo\Core\Metric\Scalar;
 use Testo\Core\Metric\Time;
-use Testo\Core\Metric\Unit;
 
 /**
  * Benchmark measurements as data rather than as the ASCII table the terminal prints.
diff --git a/core/Output/Teamcity/Teamcity/TeamcityMetricType.php b/core/Output/Teamcity/Teamcity/TeamcityMetricType.php
index 62fea0b2..0f29b6de 100644
--- a/core/Output/Teamcity/Teamcity/TeamcityMetricType.php
+++ b/core/Output/Teamcity/Teamcity/TeamcityMetricType.php
@@ -5,11 +5,11 @@
 namespace Testo\Output\Teamcity\Teamcity;
 
 use Testo\Core\Metric\Memory;
-use Testo\Core\Metric\Metric;
+use Testo\Metric\Unit;
+use Testo\Metric\Metric;
 use Testo\Core\Metric\Percent;
 use Testo\Core\Metric\Scalar;
 use Testo\Core\Metric\Time;
-use Testo\Core\Metric\Unit;
 
 /**
  * The number dimensions a TeamCity `testMetadata` message can carry, and the conversion of a Core
@@ -39,34 +39,13 @@ enum TeamcityMetricType: string
     public static function convert(Metric $metric): array
     {
         $unit = $metric->unit;
-        $value = $metric->value;
 
         return match (true) {
-            $unit instanceof Time => [self::Milliseconds, self::timeToMs($unit, $value)],
-            $unit instanceof Memory => [self::Bytes, self::memoryToBytes($unit, $value)],
-            $unit instanceof Percent => [self::Percent, $value],
-            $unit instanceof Scalar => [self::Number, $value],
-            default => [self::Number, $value],
-        };
-    }
-
-    private static function timeToMs(Time $unit, int|float $value): int|float
-    {
-        return match ($unit) {
-            Time::Nanoseconds => $value / 1_000_000,
-            Time::Microseconds => $value / 1_000,
-            Time::Milliseconds => $value,
-            Time::Seconds => $value * 1_000,
-        };
-    }
-
-    private static function memoryToBytes(Memory $unit, int|float $value): int|float
-    {
-        return match ($unit) {
-            Memory::Bytes => $value,
-            Memory::Kilobytes => $value * 1024,
-            Memory::Megabytes => $value * 1024 * 1024,
-            Memory::Gigabytes => $value * 1024 * 1024 * 1024,
+            $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/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/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/Teamcity/TeamcityMetricTypeTest.php b/tests/Output/Unit/Teamcity/TeamcityMetricTypeTest.php
index 7d85a284..0284b518 100644
--- a/tests/Output/Unit/Teamcity/TeamcityMetricTypeTest.php
+++ b/tests/Output/Unit/Teamcity/TeamcityMetricTypeTest.php
@@ -7,7 +7,7 @@
 use Testo\Assert;
 use Testo\Codecov\Covers;
 use Testo\Core\Metric\Memory;
-use Testo\Core\Metric\Metric;
+use Testo\Metric\Metric;
 use Testo\Core\Metric\Percent;
 use Testo\Core\Metric\Scalar;
 use Testo\Core\Metric\Time;
@@ -21,31 +21,49 @@ 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.1, Time::Microseconds)),
-            [TeamcityMetricType::Milliseconds, 5.1 / 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]);
+        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::Kilobytes)),
-            [TeamcityMetricType::Bytes, 2048]);
-        Assert::same(TeamcityMetricType::convert(new Metric(3, Memory::Megabytes)),
-            [TeamcityMetricType::Bytes, 3 * 1024 * 1024]);
+        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]);
+        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],
+        );
     }
 }