Document tests

9 files changed, 53 insertions, 0 deletions

diff --git a/docs/tests.md b/docs/tests.md
new file mode 100644
index 0000000..b65fb66
--- /dev/null
+++ b/docs/tests.md
@@ -0,0 +1,11 @@
+Automated testing
+=================
+
+centaur comes with a suite of automated tests. Run
+    make check
+in the top-level directory to build elfucli and run the tests.
+
+Temporary files will be created in tests/build/ and cleaned
+up on 'make clean'.
+
+See the test scripts themselves for more specific documentation.
diff --git a/tests/01-noop32.test b/tests/01-noop32.test
index 145bae3..0192240 100644
--- a/tests/01-noop32.test
+++ b/tests/01-noop32.test
@@ -1,4 +1,8 @@
 #!/bin/sh
+
+# Test if elfu can clone a given x86-32 executable in the way expected
+# by comparing it to a reference output.
+
 source ./boilerplate.sh
 
 elfucli --input reference/putsmain32 \
diff --git a/tests/02-noop64.test b/tests/02-noop64.test
index d519c55..26b1328 100644
--- a/tests/02-noop64.test
+++ b/tests/02-noop64.test
@@ -1,4 +1,8 @@
 #!/bin/sh
+
+# Test if elfu can clone a given x86-64 executable in the way expected
+# by comparing it to a reference output.
+
 source ./boilerplate.sh
 
 elfucli --input reference/putsmain64 \
diff --git a/tests/03-injection32.test b/tests/03-injection32.test
index 235f243..52405b6 100644
--- a/tests/03-injection32.test
+++ b/tests/03-injection32.test
@@ -1,4 +1,9 @@
 #!/bin/sh
+
+# Test if elfu can inject a x86-32 object file into an x86-32
+# executable. Since both are given, we can compare the output to a
+# reference file.
+
 source ./boilerplate.sh
 
 elfucli --input reference/putsmain32 \
diff --git a/tests/04-injection64.test b/tests/04-injection64.test
index 5ca6237..145e817 100644
--- a/tests/04-injection64.test
+++ b/tests/04-injection64.test
@@ -1,4 +1,9 @@
 #!/bin/sh
+
+# Test if elfu can inject a x86-64 object file into an x86-64
+# executable. Since both are given, we can compare the output to a
+# reference file.
+
 source ./boilerplate.sh
 
 elfucli --input reference/putsmain64 \
diff --git a/tests/05-detour.test b/tests/05-detour.test
index c46ef2f..a2d5d06 100644
--- a/tests/05-detour.test
+++ b/tests/05-detour.test
@@ -1,4 +1,11 @@
 #!/bin/sh
+
+# 1. Inject a freshly built object file into a fresh executable.
+#    Both use a dynamically loaded function.
+# 2. Detour execution from a function in the executable to a function
+#    originating from the object file.
+# 3. Check if the new executable prints the expected changed output.
+
 source ./boilerplate.sh
 
 elfucli --input $BUILDDIR/putsmainsub \
diff --git a/tests/06-data64kb.test b/tests/06-data64kb.test
index ebeeff2..dbb2c17 100644
--- a/tests/06-data64kb.test
+++ b/tests/06-data64kb.test
@@ -1,4 +1,9 @@
 #!/bin/sh
+
+# 1. Inject a freshly built object file with a 64 KB data section into
+#    a fresh executable.
+# 2. Check if the new executable is still functional.
+
 source ./boilerplate.sh
 
 elfucli --input $BUILDDIR/putsmain \
diff --git a/tests/07-dynlink-globalvar.test b/tests/07-dynlink-globalvar.test
index 34970f5..227bc91 100644
--- a/tests/07-dynlink-globalvar.test
+++ b/tests/07-dynlink-globalvar.test
@@ -1,4 +1,11 @@
 #!/bin/sh
+
+# 1. Inject a freshly built object file into a fresh executable.
+#    Both use a dynamically loaded function and global variable.
+# 2. Detour execution from a function in the executable to a function
+#    originating from the object file.
+# 3. Check if the new executable prints the expected changed output.
+
 source ./boilerplate.sh
 
 elfucli --input $BUILDDIR/putsmainsubglobal \
diff --git a/tests/99-data256mb.test b/tests/99-data256mb.test
index 55cfcd2..e879840 100644
--- a/tests/99-data256mb.test
+++ b/tests/99-data256mb.test
@@ -1,4 +1,9 @@
 #!/bin/sh
+
+# 1. Inject a freshly built object file with a 256 MB data section
+#    into a fresh executable.
+# 2. Check if the new executable is still functional.
+
 source ./boilerplate.sh
 
 elfucli --input $BUILDDIR/putsmain \