[lmi-commits] [lmi] master e963eef 1/5: Improve unit-test documentation

[Greg Chicares]

branch: master
commit e963eeff369154897775298688d6ec430957ba63
Author: Gregory W. Chicares <gchicares@sbcglobal.net>
Commit: Gregory W. Chicares <gchicares@sbcglobal.net>

    Improve unit-test documentation
    
    * authenticity_test.cpp: Explain the not-so-obvious reason for a test.
    * path_utility_test.cpp: Discourage reuse of an abusive technique.
---
 authenticity_test.cpp | 16 ++++++++++++----
 path_utility_test.cpp |  4 ++++
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/authenticity_test.cpp b/authenticity_test.cpp
index 7b442a1..7b5bb2b 100644
--- a/authenticity_test.cpp
+++ b/authenticity_test.cpp
@@ -263,13 +263,21 @@ void PasskeyTest::CheckNominal(char const* file, int 
line) const
         );
 }
 
-/// Authenticate from a remote directory. The current directory should
-/// be the same after authentication as it was before.
+/// Authenticate from afar, to ensure non-dependence on ${PWD}.
+///
+/// By default, lmi authenticates itself at startup. Its executable
+/// and data files shouldn't need to be in any particular directory;
+/// an invocation like this:
+///   wine /opt/lmi/bin/lmi_wx_shared --data_path=/opt/lmi/data
+/// should just work. This test checks that invariant, as follows.
+///
+/// First, change ${PWD}; authenticate; and restore ${PWD}, verifying
+/// that the restoration succeeded.
 ///
 /// Authenticate also from the root directory on a different drive, on
 /// a multiple-root system. This is perforce platform specific; msw is
-/// used because it happens to be common. This test assumes that an
-/// 'F:' drive exists and is not the "current" drive; it is skipped
+/// tested because it's common and problematic. This test assumes that
+/// an 'F:' drive exists and is not the "current" drive; it is skipped
 /// if no 'F:' drive exists.
 ///
 /// BOOST !! This test traps an exception that boost-1.33.1 can throw
diff --git a/path_utility_test.cpp b/path_utility_test.cpp
index aa10cf0..18ad82a 100644
--- a/path_utility_test.cpp
+++ b/path_utility_test.cpp
@@ -168,6 +168,10 @@ void test_serial_file_path()
 
 void test_unique_filepath_with_normal_filenames()
 {
+    // Although it's okay for this unit test, using unique_filepath()
+    // as a substitute for the nonstandard mkstemp() is a bad idea.
+    // See:
+    //   https://lists.nongnu.org/archive/html/lmi/2020-08/msg00015.html
     fs::path const u = unique_filepath("/tmp/" + fs::basename(__FILE__), "");
     std::string const tmp = u.string();
     fs::path const tmpdir(fs::complete(tmp));