From 5c42b2ceaeef78ca1c249523b7d9b5cd2405df58 Mon Sep 17 00:00:00 2001
From: Daniel Stenberg <daniel@haxx.se>
Date: Mon, 3 Jan 2011 23:47:13 +0100
Subject: unittests: basic docs

---
 tests/unit/README | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 tests/unit/README

(limited to 'tests/unit')

diff --git a/tests/unit/README b/tests/unit/README
new file mode 100644
index 000000000..b4d4f6d31
--- /dev/null
+++ b/tests/unit/README
@@ -0,0 +1,73 @@
+Unit tests
+==========
+
+The goal is to add tests for *ALL* functions in libcurl. If functions are too
+big and complicated, we should split them into smaller and testable ones.
+
+Build Unit Tests
+================
+
+'./configure --enable-debug' is required for the unit tests to build. To
+enable unit tests, there will be a separate static libcurl built that will be
+used exclusively for linking unit test programs. Just build everything as
+normal, and then you can run the unit test cases as well.
+
+Run Unit Tests
+==============
+
+Unit tests are run as part of the regular test suite. If you have built
+everything to run unit tests, to can do 'make test' at the root level. Or you
+can 'cd tests' and then invoke individual unit tests with ./runtests.pl NNNN
+where NNNN is the specific test number.
+
+Debug Unit Tests
+================
+
+If a specific test fails you will get told. The test case then has output left
+in the log/ subdirectory, but most importantly you can re-run the test again
+using gdb by doing ./runtests.pl -g NNNN. That is, add a -g to make it start
+up gdb and run the same case using that.
+
+Write Unit Tests
+================
+
+We put tests that focus on an area or a specific function into a single C
+source file. The source file should be named 'unitNNNN.c' where NNNN is a
+number that starts with 1300 and you can pick the next free number.
+
+You also need a separate file called tests/data/testNNNN (using the same
+number) that describes your test case. See the test1300 file for inspiration
+and the tests/FILEFORMAT documentation.
+
+For the actual C file, here's a very simple example:
+
+----------------------- start -------------------------------
+#include <stdlib.h>
+#include "curl_config.h"
+#include "setup.h"
+
+#include "a libcurl header.h" /* from the lib dir */
+#include "curlcheck.h"
+
+static void unit_setup( void )
+{
+  /* whatever you want done first */
+}
+
+static void unit_stop( void )
+{
+  /* done before shutting down and exiting */
+}
+
+UNITTEST_START
+
+  /* here you start doing things and checking that the results are good */
+
+  fail_unless( size == 0 , "initial size should be zero" );
+  fail_if( head == NULL , "head should not be initiated to NULL" );
+ 
+  /* you end the test code like this: */
+ 
+UNITTEST_STOP
+
+----------------------- end -------------------------------
-- 
cgit v1.2.3