ci: Fix failing render-microfacet.opt test (#2048)

This test started failing sporadically recently, with output images
that looked plausible, but differed slightly from the rest of the
checked-in reference images for this test. It only failed maybe 5% of
the time, so sometimes a CI run would pass, or sometimes fail just one
job variation, or very occasional two. Rerunning the failed job would
generally succeed, but sometimes fail again.

I'll cut to the chase: We were able to trace it to all failures
happening on GitHub runners that identified themselves as "Intel(R)
Xeon(R) Platinum 8370C CPU @ 2.80GHz". When subsequent runs of the
same job variation succeded, it was always because it landed on a
runner that identified itself as "AMD EPYC 7763 64-Core Processor".

We presume that some minor HW or SW differences (perhaps in a library
with an ISA-specific code path) resulted in LSB errors that conspire
to sample different light paths on a minority of pixels, leading to a
different pattern of specular "fireflies".

The expedient fix herein is simply to commit yet another reference
image that is considered to be a "pass".

Along for the ride, discovered during my debugging:
* Rename the label of one job variant, which was incorrect.
* Add comments to the test thresholding parameters (comments ported
  from the analogous script in OIIO, making it easier to understand
  next time one of us is figuring out this code).

Signed-off-by: Larry Gritz <lg@larrygritz.com>

Author: lgritz

.github/workflows/ci.yml

@@ -475,7 +475,7 @@ jobs:
                             PUGIXML_VERSION=v1.15
                             FREETYPE_VERSION=VER-2-14-3
           - desc: clang14/C++17 llvm14 py3.10 avx2 batch-b16avx512
-            nametag: linux-latest-releases-clang
+            nametag: linux-clang14
             runner: ubuntu-22.04
             cxx_compiler: clang++
             cc_compiler: clang

testsuite/render-microfacet/ref/out-linux-intel-alt.exr

@@ -78,13 +78,24 @@ def make_relpath (path, start=os.curdir):
 command = ""
 outputs = [ "out.txt" ]    # default
 
-# Control image differencing
+# The image comparison thresholds are tricky to remember. Here's the key:
+# A test fails if more than `failpercent` of pixel values differ by more
+# than `failthresh` AND the difference is more than `failrelative` times the
+# correct pixel value, or if even one pixel differs by more than `hardfail`.
+failthresh = 0.004         # "Failure" threshold for any pixel value
+hardfail = 0.01            # Even one pixel this wrong => hard failure
+failpercent = 0.02         # Ok fo this percentage of pixels to "fail"
+failrelative = 0.001       # Ok to fail up to this amount vs the pixel value
+allowfailures = 0          # Freebie failures
+
+# Some tests are designed for the app running to "fail" (in the sense of
+# terminating with an error return code), for example, a test that is designed
+# to present an error condition to check that it issues the right error. That
+# "failure" is a success of the test! For those cases, set `failureok = 1` to
+# indicate that the app having an error is fine, and the full test will pass
+# or fail based on comparing the output files.
 failureok = 0
-failthresh = 0.004
-hardfail = 0.01
-failpercent = 0.02
-failrelative = 0.001
-allowfailures = 0
+
 idiff_program = "oiiotool"
 idiff_postfilecmd = ""
 skip_diff = int(os.environ.get("OSL_TESTSUITE_SKIP_DIFF", "0"))