From 7b1f3d7d009b1053cce3230d6e503092aee59485 Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Thu, 3 Apr 2025 17:06:08 -0700 Subject: Stats: Improve newNull and newUnitTestingHelper docs and examples * Write short one sentence standalone "brief", written in the imperative mood, separate from longer description, * Promote the `$statsHelper` variable name for newUnitTestingHelper, which emerged in usage and seems clearer in context (context by the caller is not limited to stats, but has various things, so leading with "stats..." helps). * Mark UnitTestingHelper constructor as internal, and point to the public entry point. Ref https://www.mediawiki.org/wiki/Manual:Coding_conventions/Documentation. Change-Id: I9ede1c3ff25f53690f07dbd4043927b68629044e --- includes/libs/Stats/StatsFactory.php | 23 ++++++++++-------- includes/libs/Stats/UnitTestingHelper.php | 40 ++++++++++--------------------- 2 files changed, 26 insertions(+), 37 deletions(-) diff --git a/includes/libs/Stats/StatsFactory.php b/includes/libs/Stats/StatsFactory.php index 0307a8e237c1..18bc8118cf1d 100644 --- a/includes/libs/Stats/StatsFactory.php +++ b/includes/libs/Stats/StatsFactory.php @@ -177,13 +177,13 @@ class StatsFactory { } /** - * Returns an instance of StatsFactory as a NULL value object - * as a default for consumer code to fall back to. This can also - * be used in tests environment where we don't need the full - * UDP emitter object. + * Create a no-op StatsFactory. * - * @since 1.42 + * Use this as the default in a service that takes an optional StatsFactory, + * or as null implementation in PHPUnit tests, where we don't need to send + * output to an actual network service. * + * @since 1.42 * @return self */ public static function newNull(): self { @@ -191,14 +191,17 @@ class StatsFactory { } /** - * Returns an instance of UnitTestingHelper. + * Create a stats helper for use in PHPUnit tests. * * Example: + * * ```php - * $unitTestingHelper = StatsFactory::newUnitTestingHelper(); - * $statsFactory = $unitTestingHelper->getStatsFactory() - * MyClass( $statsFactory )->execute(); - * $this->assertEquals( 1, $unitTestingHelper->count( 'example_executions_total{fooLabel="bar"}' ) ); + * $statsHelper = StatsFactory::newUnitTestingHelper(); + * + * $x = new MySubject( $statsHelper->getStatsFactory() ); + * $x->execute(); + * + * $this->assertEquals( 1, $statsHelper->count( 'example_executions_total{fooLabel="bar"}' ) ); * ``` * * @since 1.44 diff --git a/includes/libs/Stats/UnitTestingHelper.php b/includes/libs/Stats/UnitTestingHelper.php index 619dea7391ba..58ef56588e42 100644 --- a/includes/libs/Stats/UnitTestingHelper.php +++ b/includes/libs/Stats/UnitTestingHelper.php @@ -46,14 +46,17 @@ class UnitTestingHelper { private string $component = ''; private LoggerInterface $logger; + /** + * @internal Use StatsFactory::newUnitTestingHelper() instead. + */ public function __construct() { $this->cache = new StatsCache(); - $this->logger = LoggerFactory::getInstance( 'Stats::UnitTestingHelper' ); + $this->logger = LoggerFactory::getInstance( 'Stats' ); $this->factory = new StatsFactory( $this->cache, new NullEmitter(), $this->logger ); } /** - * Sets the component for the StatsFactory instance + * Set a component on the underlying StatsFactory */ public function withComponent( string $component ): self { $this->factory = $this->factory->withComponent( $component ); @@ -62,14 +65,14 @@ class UnitTestingHelper { } /** - * Returns the testing StatsFactory instance. + * Get the underlying StatsFactory, to pass to your subject under test. */ public function getStatsFactory(): StatsFactory { return $this->factory; } /** - * Returns a count of the number of samples for a given metric. + * How many samples were observed for a given metric. * * Example: * ```php @@ -81,7 +84,7 @@ class UnitTestingHelper { } /** - * Returns the last recorded sample value for a given metric. + * The last recorded sample value for a given metric. * * Example: * ```php @@ -94,7 +97,7 @@ class UnitTestingHelper { } /** - * Returns the sum of all sample values for a given metric. + * The sum of all sample values for a given metric. * * Example: * ```php @@ -110,7 +113,7 @@ class UnitTestingHelper { } /** - * Returns the max of all sample values for a given metric. + * The max of all sample values for a given metric. * * Example: * ```php @@ -128,8 +131,7 @@ class UnitTestingHelper { } /** - * Returns the median of all sample values for a given metric. - * + * The median of all sample values for a given metric. * * Example: * ```php @@ -141,8 +143,7 @@ class UnitTestingHelper { } /** - * Returns the min of all sample values for a given metric. - * + * The min of all sample values for a given metric. * * Example: * ```php @@ -159,9 +160,6 @@ class UnitTestingHelper { return $output; } - /** - * Fetches the metric instance from cache. - */ private function getMetricFromSelector( string $selector ): MetricInterface { $key = StatsCache::cacheKey( $this->component, $this->getName( $selector ) ); $metric = $this->cache->getAllMetrics()[$key] ?? null; @@ -178,9 +176,6 @@ class UnitTestingHelper { return $metric; } - /** - * Returns a subset of samples according to provided filters. - */ private function getFilteredSamples( string $selector ): array { $metric = $this->getMetricFromSelector( $selector ); $filters = $this->getFilters( $selector ); @@ -203,9 +198,6 @@ class UnitTestingHelper { return $left; } - /** - * Returns the metric name from a selector. - */ private function getName( string $selector ): string { $selector = preg_replace( '/\'/', '"', $selector ); if ( str_contains( $selector, '{' ) ) { @@ -217,9 +209,6 @@ class UnitTestingHelper { return $selector; } - /** - * Returns the filter set from a selector. - */ private function getFilters( string $selector ): array { $selector = preg_replace( '/\'/', '"', $selector ); if ( !str_contains( $selector, '{' ) && !str_contains( $selector, ',' ) ) { @@ -234,9 +223,6 @@ class UnitTestingHelper { return $output; } - /** - * Returns the components of a filter expression. - */ private function getFilterComponents( string $filter ): array { $key = null; $value = null; @@ -270,7 +256,7 @@ class UnitTestingHelper { } /** - * Returns the boolean result of stored and expected values according to the operator. + * Return the boolean result of stored and expected values according to the operator. */ private function matches( string $stored, string $expected, string $operator ): bool { if ( $operator === self::NOT_EQUALS ) { -- cgit v1.2.3