From 9c9587feca7413b34498064db19d796e1c402b51 Mon Sep 17 00:00:00 2001
From: Alexander Todorov <atodorov@redhat.com>
Date: Thu, 11 Jun 2015 08:45:37 -0400
Subject: [PATCH 02/55] add README with description of the test suite

---
 README.rst | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 README.rst

diff --git a/README.rst b/README.rst
new file mode 100644
index 00000000000..a5743ff2f96
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,72 @@
+grubby is a command line tool for updating and displaying information about
+the configuration files for the grub, lilo, elilo (ia64), yaboot (powerpc)
+and zipl (s390) boot loaders. It is primarily designed to be used from scripts
+which install new kernels and need to find information about the current boot
+environment.
+
+
+Testing grubby
+==============
+
+To execute the integrated test suite from inside the source directory run the
+command::
+
+    make test
+
+
+Test Suite Architecture
+------------------------
+
+grubby's test suite is written in Bash. The file `test.sh` contains several
+helper functions and a list of different test scenarios which are exercised
+upon execution. Important functions are:
+
+- oneTest() - test if the configuration generated by the supplied grubby
+  parameters matches a well known configuration file;
+
+- oneDisplayTest() - test grubby features that display some information,
+  checking grubby's output against well known values;
+
+- commandTest() - test if the output of some commands matches the provided
+  text. This function is only used for grub2 testing in a few places.
+
+
+Note: the test suite creates aliases for oneTest() and oneDisplayTest(), which
+are prefixed with the corresponding boot loader name. For example:
+grubTest(). eliloTest(), etc.
+
+The invocation syntax is::
+
+    testFunction config_file results_file --grubby --options
+
+For example the line::
+
+    grubTest grub.1 updargs/g1.1 --update-kernel=DEFAULT --args="root=/dev/hda1"
+    
+means execute the command::
+
+    ./grubby --grub --config-file tests/grub.1 --update-kernel=DEFAULT \
+    --args="root=/dev/hda1"
+
+and compare the resulting configuration with the file
+`tests/results/updargs/g1.1`.
+
+
+The line::
+
+    grubDisplayTest grub.1 defaultindex/0 --default-index
+
+means execute::
+
+    ./grubby --grub --config-file tests/grub.1 --default-index
+
+and compare the output with the file `tests/results/defaultindex/0`.
+
+Writing New Test Cases
+----------------------
+
+To write a new test case for grubby you need a config file which matches the
+initial test conditions (either existing one or a new one), provide a 
+results file (likely a new one) which contains the expected configuration or
+output and finally add a call to the test function(s) using the desired grubby
+parameters in an appropriate section of `test.sh`.
-- 
2.17.1