From 0cd0f6f3f541f68fd5eabfc36f3ac724bfffde87 Mon Sep 17 00:00:00 2001
From: Aaron Taylor <ataylor@subgeniuskitty.com>
Date: Fri, 27 Mar 2020 19:59:26 -0700
Subject: [PATCH] Updates to `tests/` for release. Mostly adding comments and
 improving the README.

---
 ...owcontrol_unconditional_jump_to_label.pvvs |  2 +-
 tests/Makefile                                |  2 +-
 tests/README.md                               | 44 ++++++++++++++++++-
 tests/vv_test.py                              | 17 +++++--
 4 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/tests/4002_flowcontrol_unconditional_jump_to_label.pvvs b/tests/4002_flowcontrol_unconditional_jump_to_label.pvvs
index 8e0e6d9..7973bcb 100644
--- a/tests/4002_flowcontrol_unconditional_jump_to_label.pvvs
+++ b/tests/4002_flowcontrol_unconditional_jump_to_label.pvvs
@@ -1,5 +1,5 @@
 # This test verifies the flow control IMP for marking labels and
-# unconditionally jumping to them..
+# unconditionally jumping to them.
 
 SSSTSSSSSTN     | ST: Push +65 (ASCII A)
 NSNTSTSTSN      | FC: Unconditional jump -> '42'
diff --git a/tests/Makefile b/tests/Makefile
index 1660851..7231c49 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -1,5 +1,5 @@
 # (c) 2019 Aaron Taylor <ataylor at subgeniuskitty dot com>
-# All rights reserved.
+# See LICENSE.txt file for copyright and license details.
 
 all: test
 
diff --git a/tests/README.md b/tests/README.md
index ba26732..9a3e0f9 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -1 +1,43 @@
-This folder contains tests for `vvi` that are called from `vv_test.py`.
+# Overview #
+
+This folder contains tests for the VVhitespace interpreter (`vvi`).
+
+# Instructions #
+
+Edit the shebang in `vv_test.py` to match your environment. For example:
+
+    FreeBSD 12: #!/usr/local/bin/python3.6
+    Debian 9  : #!/usr/bin/python3
+
+Build `vvc` and `vvi` in the source tree, if you haven't already.
+
+    vvs-repo/tests % cd .. && make clean all && cd tests
+
+Alternatively, edit the configuration block in `vv_test.py` to provide
+appropriate paths relative to this `tests` folder. 
+
+    compiler_path = '../vvc'
+    interpreter_path = '../vvi'
+
+With configuration now complete, execute the tests via `make test`.  A dot will
+appear for every successfully completed test. For example:
+
+    vvs-repo/tests % make test
+    Testing vvi:
+    .......................
+    vvs-repo/tests %
+
+If a test should fail, the name of the test will be printed in place of its
+dot.  For example, with an induced failure in the division command:
+
+    vvs-repo/tests % make test
+    Testing vvi:
+    ........
+    2004_arithmetic_division
+        Expected: A
+        Received: A113
+    ..............
+    vvs-repo/tests %
+
+If testing is aborted prematurely, say by a Ctrl-C initiated SIGINT, use `make
+clean` to remove any temporary files.
diff --git a/tests/vv_test.py b/tests/vv_test.py
index fd7ab78..fddee29 100755
--- a/tests/vv_test.py
+++ b/tests/vv_test.py
@@ -1,20 +1,23 @@
 #!/usr/local/bin/python3.6
 
 # (c) 2019 Aaron Taylor <ataylor at subgeniuskitty dot com>
-# All rights reserved.
+# See LICENSE.txt file for copyright and license details.
 
 # Quick and dirty tests for the VVhitespace interpreter.
+# Invoke directly or see README.md in this folder for more details.
 
-import os, subprocess
-
+# Configuration Options
+# All paths are relative to the PWD environment variable of the invoked script.
 compiler_path = '../vvc'
 interpreter_path = '../vvi'
 temp_file = './test.vvs'
 path_to_tests = './'
 src_extension = '.pvvs'
 
+# List of tests to perform.
+# Tests should be ordered such that later tests rely exclusively on previously tested commands.
+# Test Entry Format: ['filename_without_extension', 'string for stdin', 'string for expected stdout']
 tests = [
-        # Format: ['filename_without_extension', 'string for stdin', 'string for expected stdout']
         ['0001_push_printchar_exit', '', 'A'],
         ['1001_stack_push', '', 'A'],
         ['1002_stack_dup', '', 'AA'],
@@ -40,11 +43,17 @@ tests = [
         ['6001_push_intmin', '', '1'],
         ] 
 
+# ------------------------------------------------------------------------------
+
+import os, subprocess
+
 for test in tests:
     subprocess.run([compiler_path, '-i', path_to_tests + test[0] + src_extension, '-o', temp_file])
     result = subprocess.run([interpreter_path, '-i', temp_file], stdout=subprocess.PIPE, input=test[1].encode('utf-8'))
     if result.stdout.decode('utf-8') != test[2]:
         print('\n' + test[0])
+        print('\tExpected: ' + test[2])
+        print('\tReceived: ' + result.stdout.decode('utf-8'))
     else:
         print('.', end='', flush=True)
     os.remove(temp_file)
-- 
2.20.1