view release on metacpan or  search on metacpan

xt/win32_matrix.pl  view on Meta::CPAN

######################################################################
#
# xt/win32_matrix.pl  Run the test suite over a matrix of Windows
#                     environments, from one Windows box
#
# WHY
#   Every Windows FAIL this distribution has received passed on the
#   author's own Windows machine first.  The suite was green there
#   because it had been run once, in one environment; the smokers run it
#   in environments that differ in ways the suite turned out to care
#   about:
#
#     HOME shape         C:\home\x  C:/home/x  C:\home\x\  "C:\ho me\x"
#                        and not set at all
#     working drive      the same drive as HOME, or a different one
#                        (Windows keeps a current directory PER DRIVE)
#     ANSI code page     932 (Japanese) or 65001 (UTF-8), which decides
#                        whether a CP932 file name can exist at all
#     perl               5.005_03 ... 5.42; the smokers have sent
#                        5.8.9, 5.18.4 and 5.42.0 so far
#     the environment    a smoker has no PERL5LIB, no PERL5OPT, no
#                        PERLIO or PERL_UNICODE, no interactive STDIN,
#                        and AUTOMATED_TESTING set; the author's shell
#                        has the opposite of all of that
#
#   Each of the three t/0020 failures, and the t/0015 and t/0019 ones,
#   would have been caught here before upload.  See rule R5 in
#   t/lib/BATsh_TestOS.pm.
#
#   The environment axis is rule R6, and it is why every cell runs in a
#   SCRUBBED environment by default rather than in the author's.  A cell
#   that inherits the author's %ENV reproduces the author's box, which
#   is the one machine already known to pass; reproducing the smoker is
#   the entire point.  --env=inherited or --env=both widens it back when
#   the question is specifically whether something works interactively.
#
# USAGE
#   From the distribution root, after "perl Makefile.PL && dmake":
#
#     perl xt\win32_matrix.pl                  run the whole matrix
#     perl xt\win32_matrix.pl t\0020*.t        only these test files
#     perl xt\win32_matrix.pl --list           show the matrix, run none
#     perl xt\win32_matrix.pl --perl=C:\perl5.005_03\bin\perl.exe
#                                              run it under another perl
#                                              (repeatable)
#     perl xt\win32_matrix.pl --cp=932         only this ANSI code page
#                                              (repeatable; "-" selects
#                                              the inherited one)
#     perl xt\win32_matrix.pl --home=space-in-name
#                                              only this HOME shape
#                                              (repeatable)
#     perl xt\win32_matrix.pl --env=both       run each cell twice, once
#                                              in the scrubbed smoker
#                                              environment (the default)
#                                              and once in the inherited
#                                              one.  --env=inherited
#                                              runs only the latter
#     perl xt\win32_matrix.pl --no-other-drive skip the second working
#                                              drive and the D:..Z: probe
#                                              that looks for one
#     perl xt\win32_matrix.pl --help           this text
#
# RUNNING TIME
#   The full Windows matrix is 15 cells, or 30 when a second drive is
#   found, and every cell starts all of the test files in a fresh child
#   perl -- there is no harness to amortise the process starts.  A full
#   run therefore takes tens of minutes on Windows, where creating a
#   process is an order of magnitude dearer than it is on Unix.
#
#   Because that is long enough to be mistaken for a hang, progress is
#   printed as it happens: one dot per test file, "F" for a file that
#   failed, "x" for a cell that could not even be entered, and a line
#   per cell carrying its elapsed time.  STDOUT is unbuffered, so a
#   terminal that has stopped moving means the run is genuinely stuck
#   rather than merely slow.  The first cell's elapsed time multiplied
#   by the cell count is a good estimate for the whole run.
#
#   One thing can block before any output at all: the D:..Z: probe that
#   looks for a second working drive.  An empty optical drive, or a
#   mapped network drive whose server has gone away, can make -d on that
#   letter hang or raise a "there is no disk in the drive" dialog that
#   may open behind the console window.  --no-other-drive skips the
#   probe entirely.
#
#   Every cell is run in a child perl with a modified environment; the
#   parent's own %ENV is not disturbed.  The exit status is the number
#   of cells that failed, so it can gate a release script.