Make --test-show-details=direct the default (fix #7817, #8619)

Cabal/src/Distribution/Simple/Setup/Test.hs

@@ -92,7 +92,7 @@ defaultTestFlags  = TestFlags {
     testVerbosity   = Flag normal,
     testHumanLog    = toFlag $ toPathTemplate $ "$pkgid-$test-suite.log",
     testMachineLog  = toFlag $ toPathTemplate $ "$pkgid.log",
-    testShowDetails = toFlag Failures,
+    testShowDetails = toFlag Direct,
     testKeepTix     = toFlag False,
     testWrapper     = NoFlag,
     testFailWhenNoTestSuites = toFlag False,

changelog.d/issue-7817

@@ -0,0 +1,15 @@
+synopsis: Make --(test-)show-details=direct the default
+packages: Cabal cabal-install
+prs: #8942
+
+description: {
+
+This option leaves it up to the testing framework to decide what and how to print out,
+potentially leading to a prettier output. For example, most of the testing frameworks
+use colors, which wouldn't be seen with any other option.
+
+This comes with a tradeoff, though: Cabal will not create a log file with this option.
+If you prefer a log file, consider setting `--test-show-details=streaming` (or something
+else) manually.
+
+}

doc/README.md

@@ -11,10 +11,15 @@ http://cabal.readthedocs.io/
 
 ### How to build it
 
-Building the documentation requires Python 3 be installed
-* `> make users-guide`
-* Python on Mac OS X dislikes `LC_CTYPE=UTF-8`, unset the env var in
-terminal preferences and instead set `LC_ALL=en_US.UTF-8` or something
+Building the documentation requires Python 3 and PIP. From the root of cabal
+repository run:
+
+``` console
+make users-guide
+```
+
+Note: Python on Mac OS X dislikes `LC_CTYPE=UTF-8`, so unset the variable
+and instead set `LC_ALL=en_US.UTF-8`.
 
 ### Gitpod workflow
 

doc/cabal-commands.rst

@@ -26,7 +26,7 @@ legacy sections. We talk in detail about some global and package commands.
 
     run               Run an executable.
     repl              Open an interactive session for the given component.
-    test              Run test-suites.
+    test              Run test suites.
     bench             Run benchmarks.
 
     sdist             Generate a source distribution file (.tar.gz).
@@ -970,13 +970,22 @@ cabal bench
 (all the benchmarks in the current package by default), first ensuring
 they are up to date.
 
+``cabal bench`` inherits flags of the ``bench`` subcommand of ``Setup.hs``,
+:ref:`see the corresponding section <setup-bench>`.
+
 cabal test
 ^^^^^^^^^^
 
 ``cabal test [TARGETS] [OPTIONS]`` runs the specified test suites
 (all the test suites in the current package by default), first ensuring
 they are up to date.
 
+``cabal test`` inherits flags of the ``test`` subcommand of ``Setup.hs``
+(:ref:`see the corresponding section <setup-test>`) with one caveat: every
+``Setup.hs test`` flag receives the ``test-`` prefix if it already does
+not have one; e.g. ``--show-details`` becomes ``--test-show-details`` but
+``--test-wrapper`` remains the same.
+
 cabal exec
 ^^^^^^^^^^
 

doc/setup-commands.rst

@@ -1292,8 +1292,14 @@ the package.
 
     Determines if the results of individual test cases are shown on the
     terminal. May be ``always`` (always show), ``never`` (never show),
-    ``failures`` (show only failed results), or ``streaming`` (show all
-    results in real time).
+    ``failures`` (show only failed results), ``streaming`` (show all
+    results in real time) and ``direct`` (same as ``streaming`` but no log
+    file and possibly prettier).
+
+    Default value is ``direct``: it leaves test output untouched and does not
+    produce a log. This allows for colored output, which is popular with testing
+    frameworks. (On the other hand, ``streaming`` creates a log but looses
+    coloring.)
 
 .. option:: --test-options=options