Document tests with Doxygen

Change-Id: I97d55ce5d1f21f4a72075021d03ed90eb9e3625b
Reviewed-on: http://review.couchbase.org/20709
Reviewed-by: Sergey Avseyev <sergey.avseyev@gmail.com>
Reviewed-by: Trond Norbye <trond.norbye@gmail.com>
Tested-by: Trond Norbye <trond.norbye@gmail.com>

tests/.gitignore

@@ -0,0 +1 @@
+doc

tests/README

@@ -0,0 +1 @@
+To generate documentation for the tests, run doxygen in the current directory

tests/arithmetic-unit-test.cc

@@ -77,6 +77,10 @@ extern "C" {
     }
 }
 
+/**
+ * Common function to bootstrap an arithmetic key and set the expected/last
+ * value counter.
+ */
 static void initArithmeticKey(lcb_t instance, std::string key,
                               lcb_uint64_t value)
 {
@@ -86,6 +90,15 @@ static void initArithmeticKey(lcb_t instance, std::string key,
     arithm_val = value;
 }
 
+/**
+ * @test Arithmetic (incr)
+ * @pre initialize a global variable @c arithm_val to 0.
+ * Schedule 10 arithmetic operations. The arithmetic callback should check
+ * that the current value is one greater than @c arithm_val. Then set
+ * @c arithm_val to the current value.
+ *
+ * @post The callback's assertions succeed (see precondition)
+ */
 TEST_F(ArithmeticUnitTest, testIncr)
 {
     lcb_t instance;
@@ -104,6 +117,13 @@ TEST_F(ArithmeticUnitTest, testIncr)
     lcb_destroy(instance);
 }
 
+/**
+ * @test Arithmetic (Decr)
+ *
+ * @pre Initialize the @c arithm_val to @c 100. Decrement the key 10 times.
+ *
+ * @post See @ref testIncr for expectations
+ */
 TEST_F(ArithmeticUnitTest, testDecr)
 {
     lcb_t instance;
@@ -122,6 +142,13 @@ TEST_F(ArithmeticUnitTest, testDecr)
     lcb_destroy(instance);
 }
 
+/**
+ * @test Arithmetic (Creation)
+ * @pre Perform an arithmetic operation on a non-existent key. The increment
+ * offset is @c 0x77 and the default value is @c 0xdeadbeef
+ *
+ * @post Value upon getting the key is @c 0xdeadbeef
+ */
 TEST_F(ArithmeticUnitTest, testArithmeticCreate)
 {
     lcb_t instance;

tests/doxyfilt.pl

@@ -0,0 +1,39 @@
+#!/usr/bin/perl
+
+# Google tests don't really play nicely with Doxygen, so we need to
+# Convert the TEST_F macro into something Doxygen can eat. To do this we need
+# to convert it to a simple function declaration, and trick into thinking
+# the methods have been declared
+
+use strict;
+use warnings;
+use File::Path qw(mkpath rmtree);
+
+my $fname = $ARGV[0];
+
+my @lines;
+my %classes;
+
+open my $fh, "<", $fname or die "$fname: $!";
+while ( (my $line = <$fh>) ) {
+    my $re = qr/TEST_F\(\s*([[:alnum:]]+)\s*,\s*([[:alnum:]]+)\s*\)/;
+    my ($cls,$fn) = ($line =~ $re);
+    if ($cls) {
+        push @{$classes{$cls}}, $fn;
+        $line =~ s/TEST_F[^{]+/$cls\::$fn() /g;
+    }
+    push @lines, $line;
+}
+
+while (my ($cls,$functions) = each %classes) {
+    my $decl = "// Contents of this class auto-generated by $0\n";
+    $decl .= "class $cls {\npublic: \n";
+    foreach my $func (@$functions) {
+        $decl .= "    void $func(); \n";
+    }
+    $decl .= "};\n";
+    unshift @lines, "#line \"$fname\" 0\n";
+    unshift @lines, $decl;
+}
+
+print @lines;

tests/get-unit-test.cc

@@ -46,6 +46,20 @@ extern "C" {
     }
 }
 
+/**
+ * @test
+ * Get Miss
+ *
+ * @pre
+ * Request two non-existent keys
+ *
+ * @post
+ * Responses for both keys are received with error code
+ * @c KEY_ENOENT; response structure is not NULL, and the keys match their
+ * expected value
+ *
+ * @todo (maybe check the values too?)
+ */
 TEST_F(GetUnitTest, testGetMiss)
 {
     lcb_t instance;
@@ -78,6 +92,16 @@ extern "C" {
     }
 }
 
+/**
+ * @test
+ * Get Hit
+ *
+ * @pre
+ * Store two keys, and retrieve them
+ *
+ * @post
+ * Both keys exist, and their return code is successul
+ */
 TEST_F(GetUnitTest, testGetHit)
 {
     lcb_t instance;
@@ -109,6 +133,11 @@ extern "C" {
     }
 }
 
+/**
+ * @test Touch (Miss)
+ * @pre Schedule a touch for a non existent key with an expiry @c 666
+ * @post Touch fails with @c KEY_ENOENT
+ */
 TEST_F(GetUnitTest, testTouchMiss)
 {
     std::string key("testTouchMissKey");
@@ -138,6 +167,11 @@ extern "C" {
     }
 }
 
+/**
+ * @test Touch (Hit)
+ * @pre Store a key, and schedule a touch operation with an expiry of @c 666
+ * @post Touch succeeds.
+ */
 TEST_F(GetUnitTest, testTouchHit)
 {
     std::string key("testTouchHitKey");
@@ -171,7 +205,20 @@ extern "C" {
 
 /**
  * Adopted from smoke-test.c:test_get2
- * Tests the mixed hit/miss pattern. GET misses interleaved with hits.
+ *
+ * @test Multi Get (Interleaved)
+ *
+ * @pre
+ * Create two maps of 26 key-value pairs, one called @c kexisting and one
+ * called @c kmissing. Store the @c kexisting map but not the @c kmissing one.
+ *
+ * Create a list of GET commands interleaving keys from @c kmissing and
+ * @c kexisting. Schedule the operation
+ *
+ * @post
+ * Returned result set has exactly 52 items. All the keys from @c kmissing
+ * have @c KEY_ENOENT from their result code, and all keys from @c kexisting
+ * contain the appropriate values.
  */
 TEST_F(GetUnitTest, testMixedMultiGet)
 {

tests/http-tests.cc

@@ -73,6 +73,12 @@ extern "C" {
     }
 }
 
+/**
+ * @test HTTP (Put)
+ *
+ * @pre Create a valid view document and store it on the server
+ * @post Store succeeds and the HTTP result code is 201
+ */
 TEST_F(HttpUnitTest, testPut)
 {
     SKIP_IF_MOCK();
@@ -128,6 +134,13 @@ extern "C" {
     }
 }
 
+/**
+ * @test HTTP (Get)
+ * @pre Query a value view
+ * @post HTTP Result is @c 200, and the view contents look like valid JSON
+ * (i.e. the first non-whitespace char is a @c { and the last non-whitespace
+ * char is a @c }
+ */
 TEST_F(HttpUnitTest, testGet)
 {
     SKIP_IF_MOCK();
@@ -179,6 +192,11 @@ TEST_F(HttpUnitTest, testGet)
     lcb_destroy(instance);
 }
 
+/**
+ * @test HTTP (Bad POST params)
+ * @pre Schedule an HTTP POST request, without passing a content body
+ * @post Client returns @c EINVAL
+ */
 TEST_F(HttpUnitTest, testBadParams)
 {
     SKIP_IF_MOCK();

tests/lock-unit-test.cc

@@ -48,6 +48,20 @@ extern "C" {
     }
 }
 
+/**
+ * @test
+ * Lock (lock and unlock)
+ *
+ * @pre
+ * Set a key, and get the value specifying the lock option with a timeout
+ * of @c 10.
+ *
+ * @post
+ * Lock operation succeeds.
+ *
+ * @pre Unlock the key using the CAS from the previous get result.
+ * @post Unlock succeeds
+ */
 TEST_F(LockUnitTest, testSimpleLockAndUnlock)
 {
     LCB_TEST_REQUIRE_CLUSTER_VERSION(2);
@@ -89,6 +103,15 @@ TEST_F(LockUnitTest, testSimpleLockAndUnlock)
     lcb_destroy(instance);
 }
 
+/**
+ * @test Lock (Missing CAS)
+ *
+ * @pre
+ * Store a key and attempt to unlock it with an invalid CAS
+ *
+ * @post
+ * Error result of @c ETMPFAIL
+ */
 TEST_F(LockUnitTest, testUnlockMissingCas)
 {
     LCB_TEST_REQUIRE_CLUSTER_VERSION(2);
@@ -127,8 +150,19 @@ extern "C" {
     }
 }
 /**
- * let's append '_SLEEP' to tests which sleep, so we can exclude them for
- * 'simple' runs..
+ * @test Lock (Storage Contention)
+ *
+ * @pre
+ * Store a key, perform a GET operation with the lock option, specifying a
+ * timeout of @c 10.
+ *
+ * Then attempt to store the key (without specifying any CAS).
+ *
+ * @post Store operation fails with @c KEY_EEXISTS. Getting the key retains
+ * the old value.
+ *
+ * @pre store the key using the CAS specified from the first GET
+ * @post Storage succeeds. Get returns new value.
  */
 TEST_F(LockUnitTest, testStorageLockContention)
 {
@@ -187,6 +221,23 @@ TEST_F(LockUnitTest, testStorageLockContention)
     lcb_destroy(instance);
 }
 
+/**
+ * @test
+ * Lock (Unlocking)
+ *
+ * @pre
+ * Store a key, get it with the lock option, specifying an expiry of @c 10.
+ * Try to unlock the key (using the @c lcb_unlock function) without a valid
+ * CAS.
+ *
+ * @post Unlock fails with @c ETMPFAIL
+ *
+ * @pre
+ * Unlock the key using the valid cas retrieved from the first lock operation.
+ * Then try to store the key with a new value.
+ *
+ * @post Unlock succeeds and retrieval of key yields new value.
+ */
 TEST_F(LockUnitTest, testUnlLockContention)
 {
     LCB_TEST_REQUIRE_CLUSTER_VERSION(2);