cmd/tests: Add README doc file

[Frédéric Delanoy]

---
 programs/cmd/tests/README |  120 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 120 insertions(+), 0 deletions(-)
 create mode 100644 programs/cmd/tests/README

diff --git a/programs/cmd/tests/README b/programs/cmd/tests/README
new file mode 100644
index 0000000..dd23964
--- /dev/null
+++ b/programs/cmd/tests/README
@@ -0,0 +1,120 @@
+CMD TEST PROCEDURE
+------------------
+
+1. INTRODUCTION
+
+cmd tests are handled a bit differently than other wine tests.
+
+The tests are not written in C, but directly in the form of batch files, which
+are processed by wine cmd, then compared line by line to an associated expected
+result file.
+
+Currently, we do the equivalent of
+
+    cmd /c test_builtins.cmd == test_builtins.cmd.exp
+
+
+2. ADDING TESTS
+
+Find the relevant test section ('--- Testing foo ---'), or create it if
+necessary.
+Enter the code to be processed in the .cmd file, and the expected result in the
+associated .exp file.
+You might have to use some special keywords.
+
+
+3. KEYWORDS HANDLING
+
+Both the .cmd and .exp files can contain some keywords, that are expanded or
+treated specially at runtime.
+
+Only @space@ and @tab@ are usable in .cmd files.
+
+3.1 Spacing Characters
+
+ at space@
+ at tab@
+
+Replaced by a single space and tab character respectively.
+ at space@ should generally only be used for trailing spaces, where they can be
+difficult to spot.
+ at tab@ should always be used instead of regular tab characters.
+
+3.2 Environment
+
+Following keywords are relevant to the test environment in general:
+
+ at drive@      initial drive letter
+
+ at pwd@        initial working directory
+
+ at path@       initial non-expanded path
+
+ at shortpath@  initial expanded path with short names
+
+3.3 Test helpers
+
+ at todo_wine@
+
+Used at the start of an expected line to indicate a current failure on wine, so
+the test suite can run successfully.
+To be removed when the test eventually succeeds.
+
+ at or_broken@
+
+Used to specify alternate/broken values returned by different windows versions
+(e.g. when a specific feature isn't available, etc.)
+Can be specified multiple times.
+Test runner ignores the remainder of the line following the first @or_broken@
+(keyword included).
+
+See wine developers guide - testing section for more information
+
+3.4. Usage Example
+
+ at todo_wine@expected val at space@@or_broken at foo @tab at bar@or_broken at baz
+
+specifies
+- a failure on wine (@todo_wine@)
+- normal value is 'expected value '
+- other windows versions can return 'foo \tbar'
+- still other windows versions can return 'baz'
+
+
+4. REMARKS / TIPS & TRICKS
+
+4.1. Error Messages
+
+Don't try to match error messages: they are language/locale specific and won't
+work on all (multilingual) windows versions.
+
+Ex: don't do
+
+echo foo_expr   -> foo_val at or_broken@Echo is OFF
+
+but
+
+echo 'foo_expr' -> 'foo_val'@or_broken@''
+
+4.2. Temporary files
+
+If you need temporary batch/data files, don't add them to git, but create them
+at runtime, e.g. using "echo foo>>tmpFile", and delete them afterwards.
+
+The best way is generally to use names like foo, bar or baz, or even better a
+"mkdir foobar & cd foobar" at start and "cd .. & rd /s/q foobar" at the end of
+your tests, if appropriate.
+
+4.2. Processed File
+
+The result file (processed .cmd file) and error file are deleted after usage.
+If you want to check its contents, you can temporarily comment/delete the lines
+
+DeleteFileA("test.out");
+DeleteFileA("test.err");
+
+in programs/cmd/tests/batch.c
+
+--
+Frédéric Delanoy
+frederic.delanoy at gmail.com
-- 
1.7.6