Added example of framework usagev0.1.0

10 files changed, 326 insertions, 4 deletions

diff --git a/example/Makefile b/example/Makefile
new file mode 100644
index 0000000..ede4dd4
--- /dev/null
+++ b/example/Makefile
@@ -0,0 +1,13 @@
+SRCS = add-tests.c calc.c sub-tests.c tests.c
+OBJS = $(SRCS:.c=.o)
+
+all: example
+
+clean:
+	$(RM) *.o *~ example
+
+example: $(OBJS)
+	$(CC) -o example $(OBJS)
+
+.c.o:
+	$(CC) -c $< -o $@
diff --git a/example/add-tests.c b/example/add-tests.c
new file mode 100644
index 0000000..93c361a
--- /dev/null
+++ b/example/add-tests.c
@@ -0,0 +1,141 @@
+/* ==========================================================================
+    Licensed under BSD 2clause license. See LICENSE file for more information
+    Author: Michał Łyszczek <michal.lyszczek@bofc.pl>
+   ========================================================================== */
+
+#include "../mtest.h"
+#include "add-tests.h"
+#include "calc.h"
+
+/*
+ * extern declarations of mtest variables, needed for all mt_* functions to work
+ * properly
+ */
+
+mt_defs_ext();
+
+
+/* ==========================================================================
+    Tests where everything is ok.
+   ========================================================================== */
+
+
+static void add_test_valid(void)
+{
+    mt_assert(add(5, 3) == 8);
+    mt_assert(add(1, 6) == 7);
+}
+
+
+/* ==========================================================================
+    Using assert when single one fails
+   ========================================================================== */
+
+
+static void add_test_invalid_single_assert(void)
+{
+    mt_assert(add(1, 2) == 3);
+
+    /*
+     * this assertion will fail and function will return
+     */
+
+    mt_assert(add(3, 2) == 6);
+
+    /*
+     * so this code won't be even executed
+     */
+
+    mt_assert(add(4, 2) == 6);
+}
+
+
+/* ==========================================================================
+    Test where 2 asserts fails, but only one is printed to terminal
+   ========================================================================== */
+
+
+static void add_test_invalid_multi_assert(void)
+{
+    mt_assert(add(1, 2) == 3);
+
+    /*
+     * this assertion will fail and function will return
+     */
+
+    mt_assert(add(3, 2) == 6);
+
+    /*
+     * so this code won't be even executed
+     */
+
+    mt_assert(add(4, 2) == 6);
+
+    /*
+     * and this assertion fail won't be printed to the terminal
+     */
+
+    mt_assert(add(3, 5) == 7);
+}
+
+
+/* ==========================================================================
+    Test where single fail assert fails
+   ========================================================================== */
+
+
+static void add_test_invalid_single_fail(void)
+{
+    mt_fail(add(1, 2) == 3);
+
+    /*
+     * this will fail the test, but test will continue
+     */
+
+    mt_fail(add(3, 2) == 6);
+
+    /*
+     * so this test will be performed
+     */
+
+    mt_fail(add(4, 2) == 6);
+}
+
+
+/* ==========================================================================
+    Tests where two fail asserts fails, and both are printed to terminal
+   ========================================================================== */
+
+
+static void add_test_invalid_multi_fail(void)
+{
+    mt_fail(add(1, 2) == 3);
+
+    /*
+     * this will fail the test, but test will continue
+     */
+
+    mt_fail(add(3, 2) == 6);
+    mt_fail(add(4, 2) == 6);
+
+    /*
+     * and this will fail to, printing assert information to the terminal
+     */
+
+    mt_fail(add(3, 5) == 7);
+}
+
+
+/* ==========================================================================
+    Test group that executes all tests for 'add' function
+   ========================================================================== */
+
+
+void add_tests(void)
+{
+    mt_run(add_test_valid);
+    mt_run(add_test_invalid_single_assert);
+    mt_run(add_test_invalid_multi_assert);
+    mt_run(add_test_invalid_single_fail);
+    mt_run(add_test_invalid_multi_fail);
+}
diff --git a/example/add-tests.h b/example/add-tests.h
new file mode 100644
index 0000000..5bca613
--- /dev/null
+++ b/example/add-tests.h
@@ -0,0 +1,11 @@
+/* ==========================================================================
+    Licensed under BSD 2clause license. See LICENSE file for more information
+    Author: Michał Łyszczek <michal.lyszczek@bofc.pl>
+   ========================================================================== */
+
+#ifndef ADD_TESTS_H
+#define ADD_TESTS_H 1
+
+void add_tests(void);
+
+#endif
diff --git a/example/calc.c b/example/calc.c
new file mode 100644
index 0000000..8c5d61b
--- /dev/null
+++ b/example/calc.c
@@ -0,0 +1,11 @@
+/* ==========================================================================
+    Licensed under BSD 2clause license. See LICENSE file for more information
+    Author: Michał Łyszczek <michal.lyszczek@bofc.pl>
+   ========================================================================== */
+
+
+#include "calc.h"
+
+
+int add(int a, int b) { return a + b; }
+int sub(int a, int b) { return a - b; }
diff --git a/example/calc.h b/example/calc.h
new file mode 100644
index 0000000..70950ba
--- /dev/null
+++ b/example/calc.h
@@ -0,0 +1,12 @@
+/* ==========================================================================
+    Licensed under BSD 2clause license. See LICENSE file for more information
+    Author: Michał Łyszczek <michal.lyszczek@bofc.pl>
+   ========================================================================== */
+
+#ifndef CALC_H
+#define CALC_H 1
+
+int add(int a, int b);
+int sub(int a, int b);
+
+#endif
diff --git a/example/readme.md b/example/readme.md
new file mode 100644
index 0000000..496ee18
--- /dev/null
+++ b/example/readme.md
@@ -0,0 +1,52 @@
+About
+=====
+
+This is example usage of **mtest** framework
+
+Description
+===========
+
+  * add-tests
+    This file contains various tests presenting how mt_assert and mt_fail works.
+    This also presents that tests can be called from main using single
+    test_group function
+
+  * sub-tests
+    Tests with public interfaces that are used directly from the main function
+    without any test group functions
+
+  * calc
+    file contains functions that are being tested. Black magic happens here,
+    don't be upsed if you don't understand what is going on here.
+
+  * tests
+    main function, calls test group for add tests, and call directly tests from
+    sub-tests. Also includes single test inside.
+
+Run
+===
+
+Just do make && ./example to see output. If you are lazy, no worries, output is
+included below
+
+Output
+======
+
+~~~{.sh}
+$ ./example
+ok 1 - add_test_valid
+# assert 43: add_test_invalid_single_assert, add(3, 2) == 6
+not ok 2 - add_test_invalid_single_assert
+# assert 66: add_test_invalid_multi_assert, add(3, 2) == 6
+not ok 3 - add_test_invalid_multi_assert
+# assert 95: add_test_invalid_single_fail, add(3, 2) == 6
+not ok 4 - add_test_invalid_single_fail
+# assert 118: add_test_invalid_multi_fail, add(3, 2) == 6
+# assert 125: add_test_invalid_multi_fail, add(3, 5) == 7
+not ok 5 - add_test_invalid_multi_fail
+ok 6 - sub_test_valid
+# assert 20: sub_test_invalid, sub(5, 3) == 5
+not ok 7 - sub_test_invalid
+ok 8 - sub_test
+1..8
+~~~
diff --git a/example/sub-tests.c b/example/sub-tests.c
new file mode 100644
index 0000000..c512e54
--- /dev/null
+++ b/example/sub-tests.c
@@ -0,0 +1,21 @@
+/* ==========================================================================
+    Licensed under BSD 2clause license. See LICENSE file for more information
+    Author: Michał Łyszczek <michal.lyszczek@bofc.pl>
+   ========================================================================== */
+
+
+#include "../mtest.h"
+#include "sub-tests.h"
+#include "calc.h"
+
+mt_defs_ext();
+
+void sub_test_valid(void)
+{
+    mt_assert(sub(5, 3) == 2);
+}
+
+void sub_test_invalid(void)
+{
+    mt_assert(sub(5, 3) == 5);
+}
diff --git a/example/sub-tests.h b/example/sub-tests.h
new file mode 100644
index 0000000..3cae17b
--- /dev/null
+++ b/example/sub-tests.h
@@ -0,0 +1,12 @@
+/* ==========================================================================
+    Licensed under BSD 2clause license. See LICENSE file for more information
+    Author: Michał Łyszczek <michal.lyszczek@bofc.pl>
+   ========================================================================== */
+
+#ifndef SUB_TESTS_H
+#define SUB_TESTS_H 1
+
+void sub_test_valid(void);
+void sub_test_invalid(void);
+
+#endif
diff --git a/example/tests.c b/example/tests.c
new file mode 100644
index 0000000..f2a7c75
--- /dev/null
+++ b/example/tests.c
@@ -0,0 +1,48 @@
+#include "../mtest.h"
+
+#include "add-tests.h"
+#include "sub-tests.h"
+
+#include "calc.h"
+
+/*
+ * define global variables needed for whole mtest framework
+ */
+
+mt_defs();
+
+
+static void sub_test(void)
+{
+    mt_assert(sub(5, 4) == 1);
+}
+
+
+int main(void)
+{
+    /*
+     * we can execute test group from another file
+     */
+
+    add_tests();
+
+    /*
+     * or we can call tests directly from another file
+     */
+
+    mt_run(sub_test_valid);
+    mt_run(sub_test_invalid);
+
+    /*
+     * we can also run tests from this very file
+     */
+
+    mt_run(sub_test);
+
+    /*
+     * and at the end we call mt_return, which will print clousure information
+     * and will exit test program with apropriate return code
+     */
+
+    mt_return();
+}
diff --git a/readme.md b/readme.md
index 40526a6..913df61 100644
--- a/readme.md
+++ b/readme.md
@@ -14,8 +14,8 @@ Valid C89 compiler with *fprintf* function implemented.
 Instalation
 ===========
 
-Just copy **mtest.h** into your project tree, and include it. It's that easy. You
-can also call *make install* so **mtest** is copied into local machine. Just
+Just copy **mtest.h** into your project tree, and include it. It's that easy.
+You can also call *make install* so **mtest** is copied into local machine. Just
 mind that **mtest** will become your build dependency, and it's so small, it is
 usually not necessary. The good thing of calling **make install** is that, man
 pages will be installed in your system, so you can have quick overview of the
@@ -32,8 +32,9 @@ it's a proof that unit testing can be very easy to implement.
 Examples
 ========
 
-memperf (https://github.com/mlyszczek/memperf) makes use of this framework for
-its tests. Tests results are integrated with automake **make check** call.
+Example test is in *example* directory, also memperf
+(https://github.com/mlyszczek/memperf) makes use of this framework for its
+tests. Tests results are integrated with automake **make check** call.
 
 License
 =======