diff --git a/tests/README b/tests/README
new file mode 100644
--- /dev/null
+++ b/tests/README
@@ -0,0 +1,27 @@
+A simple testing framework
+
+This finds all scripts in the test directory named test-* and executes
+them. The scripts can be either shell scripts or Python. Each test is
+run in a temporary directory that is removed when the test is complete.
+
+A test-<x> succeeds if the script returns success and its output
+matches test-<x>.out. If the new output doesn't match, it is stored in
+test-<x>.err.
+
+There are some tricky points here that you should be aware of when
+writing tests:
+
+- hg commit and hg up -m want user interaction
+
+  for commit use -t "text"
+  for hg up -m, set HGMERGE to something noninteractive (like true or merge)
+
+- changeset hashes will change based on user and date which make
+  things like hg history output change
+
+  use commit -t "test" -u test -d "0 0"
+
+- diff will show the current time
+
+  use hg diff | sed "s/\(\(---\|+++\).*\)\t.*/\1/" to strip dates
+