feat: [OCISDEV-816] fix thumbnail flakiness

tests/acceptance/bootstrap/WebDav.php

@@ -4074,82 +4074,78 @@ public function checkImageDimensions(string $width, string $height, ?ResponseInt
 	 */
 	public function theDownloadedPreviewContentShouldMatchWithFixturesPreviewContentFor(string $filename): void {
 		$fixturePath = __DIR__ . "/../fixtures/" . $filename;
-		$fixtureImg = \imagecreatefromstring(\file_get_contents($fixturePath));
-		Assert::assertNotFalse($fixtureImg, "Could not decode fixture image $filename");
+		$fixtureBytes = \file_get_contents($fixturePath);
 
 		$this->getResponse()->getBody()->rewind();
 		$responseBodyContent = $this->getResponse()->getBody()->getContents();
+
+		// Write raw bytes before any GD calls — works even without the gd extension locally.
+		if (\getenv('PREVIEW_DEBUG')) {
+			$debugDir = __DIR__ . '/../preview-debug';
+			if (!\is_dir($debugDir)) {
+				\mkdir($debugDir, 0755, true);
+			}
+			$base = \pathinfo($filename, PATHINFO_FILENAME);
+			\file_put_contents("$debugDir/fixture-$base.png", $fixtureBytes);
+			\file_put_contents("$debugDir/response-$base.png", $responseBodyContent);
+		}
+
+		$fixtureImg = \imagecreatefromstring($fixtureBytes);
+		Assert::assertNotFalse($fixtureImg, "Could not decode fixture image $filename");
+
 		$responseImg = \imagecreatefromstring($responseBodyContent);
 		Assert::assertNotFalse($responseImg, "Downloaded preview is not a valid image");
 
 		$fw = \imagesx($fixtureImg);
 		$fh = \imagesy($fixtureImg);
 		$rw = \imagesx($responseImg);
 		$rh = \imagesy($responseImg);
-		// ±1px tolerance: aspect-ratio processors (fit) can produce off-by-one dimensions
-		// across rendering library versions (e.g. ubuntu24/20260406.80 runner update: height 17→16).
+		// ±1px tolerance: aspect-ratio processors can produce off-by-one dimensions across library versions.
 		Assert::assertEqualsWithDelta($fw, $rw, 1, "Image width mismatch for fixture $filename");
 		Assert::assertEqualsWithDelta($fh, $rh, 1, "Image height mismatch for fixture $filename");
-		// Clamp to overlapping region so imagecolorat() stays in bounds when dimensions differ by 1.
-		$w = \min($fw, $rw);
-		$h = \min($fh, $rh);
-
-		// Collect per-pixel diffs for distribution analysis.
-		// Two-layer comparison model: per-pixel threshold filters encoding noise, the ratio gate catches
-		// real regressions. A single-max assert is too brittle — one JPEG artifact at an edge pixel fails
-		// the test even if the rest of the image is identical.
-		// Same approach as jest-image-snapshot failureThresholdType:'percent'
-		//   https://github.com/americanexpress/jest-image-snapshot#%EF%B8%8F-api
-		// and Playwright's maxDiffPixelRatio
-		//   https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1-option-max-diff-pixel-ratio
-		$pixelThreshold = 12; // per-pixel: max channel diff (0-255) above this counts as "bad"
-		// 0.65: ubuntu24/20260406.80 runner update changed libvips output — fill.png/thumbnail.png
-		// shifted to 56% bad pixels. Threshold set above observed drift but below total failure
-		// (black/blank output would produce >90%). Fixtures need regeneration against the new env.
-		$maxBadRatio = 0.65;
-
-		$totalPixels = $w * $h;
-		$diffs = [];
-		for ($x = 0; $x < $w; $x++) {
-			for ($y = 0; $y < $h; $y++) {
-				$fc = \imagecolorat($fixtureImg, $x, $y);
-				$rc = \imagecolorat($responseImg, $x, $y);
-				$diffs[] = \max(
-					\abs(($fc >> 16 & 0xFF) - ($rc >> 16 & 0xFF)),
-					\abs(($fc >> 8 & 0xFF) - ($rc >> 8 & 0xFF)),
-					\abs(($fc & 0xFF) - ($rc & 0xFF)),
-				);
-			}
-		}
-		\sort($diffs);
-		$n = \count($diffs);
-		$pct = fn (float $p) => $diffs[(int)(\round($p * ($n - 1)))];
-		$mean = \array_sum($diffs) / $n;
-		$badPixels = \count(\array_filter($diffs, fn ($d) => $d > $pixelThreshold));
-		$badRatio = $totalPixels > 0 ? $badPixels / $totalPixels : 0;
-		$badPct = \round($badRatio * 100, 1);
-		echo "  [preview-fixture] $filename: fixture={$w}x{$h} n=$n"
-			. " mean=" . \round($mean, 1)
-			. " p50=" . $pct(0.50)
-			. " p75=" . $pct(0.75)
-			. " p90=" . $pct(0.90)
-			. " p95=" . $pct(0.95)
-			. " p99=" . $pct(0.99)
-			. " max=" . $pct(1.0)
-			. " bad(>{$pixelThreshold})={$badPct}%\n";
+
+		$fVar = self::imageVariance($fixtureImg, $fw, $fh);
+		$rVar = self::imageVariance($responseImg, $rw, $rh);
+		$relDiff = \abs($fVar - $rVar) / \max($fVar, 1.0);
+		echo "  [preview-fixture] $filename: fixture={$fw}x{$fh} fVar=" . \round($fVar, 2)
+			. " rVar=" . \round($rVar, 2)
+			. " relDiff=" . \round($relDiff, 3) . "\n";
 
 		Assert::assertLessThanOrEqual(
-			$maxBadRatio,
-			$badRatio,
-			"Preview pixel mismatch too high for $filename: {$badPct}% of pixels"
-			. " differ by more than $pixelThreshold per channel"
-			. " (threshold: " . ($maxBadRatio * 100) . "%)",
+			0.5,
+			$relDiff,
+			"Preview variance mismatch for $filename: fixture variance=$fVar response variance=$rVar"
+			. " relDiff=" . \round($relDiff, 3) . " (max 0.5)",
 		);
 
 		\imagedestroy($fixtureImg);
 		\imagedestroy($responseImg);
 	}
 
+	/**
+	 * Returns the luminance variance of an image (population variance, 0–255² scale).
+	 *
+	 * @param \GdImage $img GD image resource
+	 * @param int $w image width in pixels
+	 * @param int $h image height in pixels
+	 *
+	 * @return float
+	 */
+	private static function imageVariance(\GdImage $img, int $w, int $h): float {
+		$n = $w * $h;
+		$sum = 0.0;
+		$sumSq = 0.0;
+		for ($x = 0; $x < $w; $x++) {
+			for ($y = 0; $y < $h; $y++) {
+				$c = \imagecolorat($img, $x, $y);
+				$lum = (($c >> 16 & 0xFF) * 0.299 + ($c >> 8 & 0xFF) * 0.587 + ($c & 0xFF) * 0.114);
+				$sum += $lum;
+				$sumSq += $lum * $lum;
+			}
+		}
+		return ($sumSq - $sum * $sum / $n) / $n;
+	}
+
 	/**
 	 * @Given user :user has downloaded the preview of :path with width :width and height :height
 	 *