docs(test_generator.org): update test documentation

Signed-off-by: Norwid Behrnd <nbehrnd@yahoo.com>

test_generator.org

@@ -12,34 +12,44 @@
   The application =appendfilename= by Karl Voit /et al./ ([[https://github.com/novoid/appendfilename][source]])
   allows the programmatic addition of user defined strings to one or
   multiple already existing file names (e.g., add =travel= to file
-  =example.jpg= to yield =example_travel.jpg=).  By the command =C-c
+  =example.jpg= to yield =example_travel.jpg=).  This file
-  C-v t=, Emacs may use the present =.org= file to (re)generate a
+  =test_generator.org= provides the files for a programmatic test
-  tangled test script, file =test_appendfilename.py= for a
+  of =appendfilename= by means of /code tangle/ from Emacs orgmode.
-  programmatic testing by [[https://docs.pytest.org/en/latest/][pytest]].  (Though =pytest= is not part of the
-  Python standard library, it may be obtained easily e.g., from [[https://pypi.org/project/pytest/][PyPi]].)
-  Optionally, the testing may be run by the equally tangled
-  =Makefile=.
 
 * Deployment
 
-  The programmatic tests are set up for pytest for Python 3.  It
+  The tests presume a working installation of Python 3.  After the
-  however depends on your installation (and in case of Linux, the
+  activation of a virtual environment, one suitable approach is to
-  authors of your Linux distribution ([[https://github.com/pytest-dev/pytest/discussions/9481][reference]])) if this utility may
+  resolve the dependencies by
-  be started by =pytest= (e.g., the pattern in pytest's manual), or by
-  =pytest-3= by either one of the pattern below:
 
-  #+begin_src bash :tangle no
+  #+begin_src shell :tangle no
-pytest -v test_appendfilename.py
+python -m pip install -r requirements.txt
-pytest-3 -v test_appendfilename.py
   #+end_src
 
-  As of writing, the later pattern is the to be used e.g., in Linux
+  with data by PyPI.  Subsequently, the tests can be launched by
-  Debian 12/bookworm (branch testing) to discern pytest (for
-  contemporary Python 3) from pytest (for legacy Python 2).
 
-  The =Makefile= this =org= file provides for convenience running
+  #+begin_src shell :tangle no
-  these tests assumes the later syntax pattern.  (It might be
+python -m pytest
-  necessary to provide the executable bit to activate the Makefile.)
+  #+end_src
+
+  where each period (=.=) indicates a passing, and each =E= a failing
+  test.  An optional flag
+
+  - =-v= allows a more verbose output to the CLI
+  - =-x= stops the sequence after the first failing test
+  - =-s= occasionally provides information e.g., about the tests' criteria
+
+  The tests are organized in sets =default=, =prepend=, and =smart=.
+  This allows to selectively run only checks which are about the
+  results by =appendfilename= in the /default/ mode, /prepend/ mode,
+  or /smart prepend/ mode alone, e.g.
+
+  #+begin_src shell :tangle no
+python -m pytest -m "prepend"
+  #+end_src
+
+  The tests were revised to work equally well in Linux Debian 13/trixie
+  (e.g., Python 3.12.6 and pytest 8.3.3) as well as Windows 10.
 
 * Setup of Emacs
 
@@ -99,64 +109,36 @@ pytest-3 -v test_appendfilename.py
 
 * Building the tests
 
-** Building of the Makefile
+** Building file =pytest.ini=
 
-   The setup is for GNU Make 4.3 as provided e.g., by Linux Debian 12
+   Markers file =pytest.ini= defines and which are used in file
-   (bookworm), branch testing.  Note, the Makefile tangled is a mere
+   =test_appendfilename.py= allows to constrain the run of
-   convenient moderator for =test_appendfilename.py=; the eventual
+   =pytest=.  Rather than to launch a check on all tests, a call
-   testing of appendfilename's action does not depend on this
+   like e.g.,
-   Makefile.
-
-    #+BEGIN_SRC makefile :tangle Makefile
-# GNU Make file for the automation of pytest for appendfilename
-#
-# While the test script is written for Python 3.9.2, it depends on
-# your installation of pytest (and in case of Linux, the authors of
-# your distribution) if pytest for Python 3 is invoked either by
-# pytest, or pytest-3.  In some distributions, pytest actually may
-# invoke pyest for legacy Python 2; the tests in test_date2name.py
-# however are incompatible to this.
-#
-# Put this file like test_appendfilename.py in the root folder of
-# appendfilename fetched from PyPi or GitHub.  Then run
-#
-# chmod +x *
-# make ./Makefile
-#
-# to run the tests.  If you want pytest to exit the test sequence
-# right after the first test failing, use the -x flag to the
-# instructions on the CLI in addition to the verbosity flag to (-v).
-
-# pytest -v test_appendfilename.py     # the pattern by pytest's manual
-pytest-3 -v test_appendfilename.py   # the alternative pattern (e.g., Debian 12)
-    #+end_src
-
-** Building a pytest.ini
-
-   This file defines markers to assign tests into groups.  This allows to run
-   =pytest= on a subset rather than all tests (which is set up as the default).
-   E.g., in presence of =pytest.ini=, a call like
 
    #+begin_src bash  :tangle no
-pytest-3 test_appendfilename.py -v -m "default"
+python -m pytest -m "prepend"
    #+end_src
 
-   constrains the tester's action to all tests labeled as "default" as about the
+   only checks those of set =prepend=.  At present, tests are
-   default position where the text string is added.  At present, tests are
    grouped as
-   + default; appendfilename's default string insertions
+
-   + prepend; corresponding to appendfilename's optional -p/--prepend flag, and
+   + =default= appendfilename's default string insertions
-   + smart; corresponding to appendfilename's optional --smart-prepend flag
+   + =prepend= corresponding to either appendfilename's optional =-p=
-     
+     or =--prepend= flag, and
-   It is possible to run one, two, or all three groups in one run of pytest.
+   + =smart= corresponding to appendfilename's optional
-   E.g., a simultaneous check of tests belonging to either default, or prepend
+    =--smart-prepend= flag
-   optional requires the instruction
+
+   It is possible to run one, two, or all three groups in one run of
+   pytest, for instance
 
    #+begin_src bash :tangle no
 pytest-3 test_appendfilename.py -m "default and prepend" -v
    #+end_src
 
-   #+begin_src python :tangle pytest.ini
+   The content of =pytest.ini=:
+
+   #+begin_src shell :tangle pytest.ini
 [pytest]
 Markers =
     default:  appendfilename's default string insertions
@@ -164,7 +146,6 @@ Markers =
     smart:    appendfilename's optional --smart-prepend flag
    #+end_src
 
-
 ** Building the test script
 
 *** header section
@@ -222,8 +203,7 @@ PROGRAM = os.path.join("appendfilename", "__init__.py")  # Cross-platform path
 *** appendfilename, default position
 
     Departing with file =test.txt=, appendfile's addition of =example= should
-    yield =test example.txt=.  Testing so far skips the addition of string
+    yield =test example.txt=.
-    containing spaces, as well as the implicit spacing.
 
     #+begin_src python :tangle test_appendfilename.py
 # The following section tests the applications default pattern where a string
@@ -370,8 +350,8 @@ def test_prepend(arg1, arg2, arg3, arg4):
 
     Here, the additional string follows the time stamp, and leads
     the rest of the file's file name.  Of five patterns provided by
-    `date2name`, only `--withtime` and the default YYYY-MM-DD are
+    =date2name=, only =--withtime= and the default YYYY-MM-DD are
-    checked.  The other three (`--compact`, `--month`, and `--short`)
+    checked.  The other three (=--compact=, =--month=, and =--short=)
     are muted for their pattern still different to the other two.
     Equally see [[https://github.com/novoid/appendfilename/issues/15]]
     and [[https://github.com/novoid/appendfilename/issues/16]].