diff --git a/test/.gitignore b/test/.gitignore
index 3103c757e..8612fc160 100644
--- a/test/.gitignore
+++ b/test/.gitignore
@@ -1,2 +1,3 @@
+sharness/
 test-results/
 trash directory.*.sh/
diff --git a/test/Makefile b/test/Makefile
index 85be73662..489beaab6 100644
--- a/test/Makefile
+++ b/test/Makefile
@@ -5,6 +5,7 @@
 #
 
 T = $(sort $(wildcard t[0-9][0-9][0-9][0-9]-*.sh))
+SHARNESS = sharness/sharness.sh
 
 all: clean deps $(T) aggregate
 
@@ -20,21 +21,22 @@ aggregate:
 	@echo "*** $@ ***"
 	./test-aggregate-results.sh
 
-deps: ipfs sharness.sh random
+deps: $(SHARNESS) ipfs random
 
-# phony to ensure we re-build it every time we run tests
-ipfs:
-	cd ../cmd/ipfs && go build
-	cp ../cmd/ipfs/ipfs ipfs
-
-sharness.sh:
+$(SHARNESS):
 	@echo "*** installing $@ ***"
 	./install-sharness.sh
 
-.PHONY: all clean $(T) aggregate ipfs
+# phony to ensure we re-build it every time we run tests
+ipfs:
+	@echo "*** installing $@ ***"
+	cd ../cmd/ipfs && go build
+	cp ../cmd/ipfs/ipfs ipfs
 
 random:
 	@echo "*** installing $@ ***"
 	go get github.com/jbenet/go-random/random
 	go install github.com/jbenet/go-random/random
 	cp `which random` random
+
+.PHONY: all clean $(T) aggregate ipfs random
diff --git a/test/README.md b/test/README.md
new file mode 100644
index 000000000..8bef3680c
--- /dev/null
+++ b/test/README.md
@@ -0,0 +1,26 @@
+# ipfs whole tests using the [sharness framework](https://github.com/mlafeldt/sharness/)
+
+## Running all the tests
+
+Just use `make` in this directory to run all the tests.
+
+## Running just one test
+
+You can run only one test script by launching it like a regular shell
+script:
+
+```
+$ ./t0010-basic-commands.sh
+```
+
+## Sharness
+
+When running "make" in this directory for the first time, sharness
+will be downloaded from its github repo and installed in a "sharness"
+directory.
+
+Please do not change anything in the "sharness" directory.
+
+If you really need some changes in sharness, please fork it from
+[its cannonical repo](https://github.com/mlafeldt/sharness/) and
+send pull requests there.
\ No newline at end of file
diff --git a/test/install-sharness.sh b/test/install-sharness.sh
index 871ebb690..2caf97712 100755
--- a/test/install-sharness.sh
+++ b/test/install-sharness.sh
@@ -16,6 +16,11 @@ shash=eeaf96630fc25ec58fb678b64ef9772d5eb92f64
 afile=aggregate-results.sh
 ahash=948d6bc03222c5c00a1ed048068508d5ea1cce59
 
+die() {
+  echo >&2 $@
+  exit 1
+}
+
 verified_download() {
   file=$1
   hash1=$2
@@ -34,6 +39,8 @@ verified_download() {
   return 0
 }
 
+mkdir -p sharness || die "Could not create 'sharness' directory"
+cd sharness || die "Could not cd into 'sharness' directory"
 
 verified_download "$sfile" "$shash"; sok=$?
 verified_download "$afile" "$ahash"; aok=$?
diff --git a/test/test-aggregate-results.sh b/test/test-aggregate-results.sh
index eea4b7154..10838815a 100755
--- a/test/test-aggregate-results.sh
+++ b/test/test-aggregate-results.sh
@@ -6,7 +6,7 @@
 # MIT Licensed; see the LICENSE file in this repository.
 #
 
-SHARNESS_AGGREGATE="./aggregate-results.sh"
+SHARNESS_AGGREGATE="sharness/aggregate-results.sh"
 
 test -f "$SHARNESS_AGGREGATE" || {
 	echo >&2 "Cannot find: $SHARNESS_AGGREGATE"
diff --git a/test/test-lib.sh b/test/test-lib.sh
index d9c19395f..a8877418b 100644
--- a/test/test-lib.sh
+++ b/test/test-lib.sh
@@ -18,7 +18,7 @@ if test `which ipfs` != $(pwd)/ipfs; then
 	exit 1
 fi
 
-SHARNESS_LIB="./sharness.sh"
+SHARNESS_LIB="sharness/sharness.sh"
 
 . "$SHARNESS_LIB" || {
 	echo >&2 "Cannot source: $SHARNESS_LIB"