aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/a_simple_example.c52
-rw-r--r--doc/usage.pdfbin0 -> 138351 bytes
-rw-r--r--doc/usage.tex207
3 files changed, 259 insertions, 0 deletions
diff --git a/doc/a_simple_example.c b/doc/a_simple_example.c
new file mode 100644
index 0000000..fb7d774
--- /dev/null
+++ b/doc/a_simple_example.c
@@ -0,0 +1,52 @@
+#include "simple-test.h"
+#include "header_with_stuff_to_be_tested.h"
+
+BEGIN_TEST
+
+/* a simple test using only stack mem */
+TEST("description of the first test")
+{
+ int var1=2;
+ int var2=4;
+
+ /* add is a function included from our hypothetical
+ * header_with_stuff_to_be_tested */
+ EXPECT_INT("error message shown on failing",
+ var1+var2, add(var1, var2));
+}
+
+/* this test uses heap memory, so things get a bit
+ * more complicated */
+TEST("this is the second test")
+{
+ /* first, ensure all your pointers which will
+ * point to heap mem are declared */
+ char *heap_string=NULL;
+
+ /* next, declare a list of statements to be
+ * called to clean up memory once the test
+ * is completed */
+ CLEANUP(
+ if(heap_string != NULL)
+ free(heap_string);
+ );
+
+ /* then, define the body of the test */
+
+ /* STATE can be used to report (with pretty
+ * formatting) the current state within the
+ * test, which may be useful in the case of
+ * a segfault */
+ STATE("grabbing heap string");
+
+ heap_string=get_heap_string_value();
+
+ EXPECT_STR("i suck at grabbing pointers!",
+ "expected value", heap_string);
+
+ /* finally, call RETURN(); to run the
+ * cleanup code and continue */
+ RETURN();
+}
+
+END_TEST
diff --git a/doc/usage.pdf b/doc/usage.pdf
new file mode 100644
index 0000000..fb6f9c7
--- /dev/null
+++ b/doc/usage.pdf
Binary files differ
diff --git a/doc/usage.tex b/doc/usage.tex
new file mode 100644
index 0000000..6494ee5
--- /dev/null
+++ b/doc/usage.tex
@@ -0,0 +1,207 @@
+%%%%%%%%%%%
+% SETUP %
+%%%%%%%%%%%
+
+\documentclass[a4paper]{article}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage[usenames,x11names,table]{xcolor}
+
+\usepackage{listings}
+\usepackage{enumitem}
+\usepackage{graphicx}
+\usepackage{framed}
+\usepackage{calc}
+\usepackage{ifthenx}
+\usepackage{tabularx}
+\usepackage{soul}
+
+%%% -------------------------------------------------------
+%%% universal formatting
+%%% -------------------------------------------------------
+
+\parindent 0pt
+\frenchspacing
+\pagestyle{empty}
+
+\setlength{\oddsidemargin}{0in}
+\setlength{\evensidemargin}{0in}
+\setlength{\marginparsep}{0in}
+\setlength{\marginparwidth}{0in}
+\setlength{\textwidth}{6.5in}
+
+\setlength{\topmargin}{0in}
+\setlength{\headsep}{0in}
+\setlength{\headheight}{0in}
+\setlength{\textheight}{9in}
+
+%%% -------------------------------------------------------
+%%% custom commands
+%%% -------------------------------------------------------
+
+% a horizontal box with coloured background
+\newcommand{\myheading}[1]{
+ {
+ \definecolor{shadecolor}{named}{Azure4}
+ \begin{snugshade*}
+ \centering\large
+ \textcolor{white}{\textbf{-- #1 --}\vphantom{p\^{E}}}
+ \end{snugshade*}
+ }
+}
+
+\newcommand{\myhl}[1]{
+ {
+ \color{Snow1}
+ \sethlcolor{Red1}
+ \hl{#1}
+ }
+}
+
+\newcommand{\mymacrow}[2]{
+ \footnotesize\textcolor{DarkOrchid3}{\textbf{#1}}: & \small #2 \\[8pt]
+}
+
+\newcommand{\mytermrow}[2]{
+ \tt\bf\small #1 & \tt\small #2 \\
+}
+
+
+
+\begin{document}
+
+ % setup
+ \frenchspacing
+
+ % C styling
+ \lstdefinestyle{customc}{
+ language=C,
+ basicstyle=\small\ttfamily,
+ breaklines=true,
+ keepspaces=true,
+ xleftmargin=\parindent,
+ % colours
+ commentstyle=\color{DodgerBlue2},
+ identifierstyle=\color{Red1},
+ keywordstyle=\color{Purple3},
+ stringstyle=\color{SpringGreen4},
+ numbers=left,
+ showstringspaces=false,
+ }
+
+
+ \myheading{usage}
+
+ Your tests should be written as a single .c file separate from
+ the body of text containing your functionality to be tested.
+ A simple example might look something like this: \\
+
+ \hrule
+ \lstset{style=customc}
+ \lstinputlisting{a_simple_example.c}
+ \hrule
+ \pagebreak
+
+ If both tests above succeed, the output will look like this:\\
+
+ \hrule
+ \vspace{8pt}
+
+ % successful output
+ \begin{tabular*}{\textwidth}{r@{\ \tt\bf :: }l}
+ \mytermrow{1}{\color{Yellow4}description of the first test}
+ \mytermrow{2}{\color{Yellow4}this is the second test}
+ \mytermrow{ }{\color{DodgerBlue2}grabbing heap string...}
+ \mytermrow{ }{\color{SpringGreen4}success!}
+ \end{tabular*}
+
+ \vspace{8pt}
+ \hrule
+ \vspace{20pt}
+
+ If the first test fails, it will look something like this:\\
+ \hrule
+ \vspace{8pt}
+
+ % failed output
+ \begin{tabular*}{\textwidth}{r@{\ \tt\bf :: }l}
+ \mytermrow{1}{\color{Yellow4}description of the first test}
+ \mytermrow{ }{\color{Red1}FAIL: error message shown on failing}
+ \mytermrow{ }{\textcolor{SpringGreen4}{\textbf{\ \ expected:}}6}
+ \mytermrow{ }{\textcolor{Red1}{\textbf{\ \ \ \ actual:}}0}
+ \end{tabular*}
+
+ \vspace{8pt}
+ \hrule
+
+ \pagebreak
+
+ \myheading{defined macros}
+ \begin{tabularx}{\textwidth}{r@{\ }X}
+ \mymacrow{BEGIN\_TEST}{
+ must appear before all tests and
+ after all global variable declarations
+ }
+ \mymacrow{END\_TEST}{
+ must appear at the end of your test
+ program
+ }
+ \mymacrow{CLEANUP(statements)}{
+ this defines a list of statements to run
+ when the test exits, either successfully or
+ on a failure. it isn't necessary for a test
+ to run, but, if it does appear, it must be
+ after the declaration of all variables to
+ which it makes reference.
+ }
+ \mymacrow{RETURN()}{
+ place at the end of a test which uses
+ CLEANUP to ensure it is called before the
+ test exits. i couldn't find any way around
+ this without using more than just one
+ header file, so i hope it isn't too annoying.
+ }
+ \mymacrow{STATE(description)}{
+ show a prettily-formatted description of the
+ program's state during a test. takes printf-style
+ arguments.
+ }
+ \mymacrow{EXPECT\_ZERO(summary, arg)}{
+ fail if \texttt{arg} does not resolve to 0
+ }
+ \mymacrow{EXPECT\_ONE(summary, arg)}{
+ fail if \texttt{arg} does not resolve to 1
+ }
+ \mymacrow{EXPECT\_GREATER\_THAN\_ZERO(summary, arg)}{
+ fail if \texttt{arg} does not resolve to a value
+ greater than 0. this will be replaced with more
+ generic integer comparisons soon.
+ }
+ \mymacrow{EXPECT\_INT(summary, arg1, arg2)}{
+ fail if \texttt{arg2} does not match the
+ expected integer value \texttt{arg1}
+ }
+ \mymacrow{EXPECT\_EQUAL\_INT(summary, arg1, arg2)}{
+ fail if \texttt{arg1} and \texttt{arg2} are
+ not equal
+ }
+ \mymacrow{EXPECT\_UNEQUAL\_INT(summary, arg1, arg2)}{
+ fail if \texttt{arg1} and \texttt{arg2} are
+ equal
+ }
+ \mymacrow{EXPECT\_STR(summary, arg1, arg2)}{
+ fail if string \texttt{arg2} does not match the
+ expected string value \texttt{arg1}
+ }
+ \mymacrow{EXPECT\_EQUAL\_STR(summary, arg1, arg2)}{
+ fail if \texttt{arg1} and \texttt{arg2} are
+ not equivalent strings
+ }
+ \mymacrow{EXPECT\_UNEQUAL\_STR(summary, arg1, arg2)}{
+ fail if \texttt{arg1} and \texttt{arg2} are
+ equivalent strings
+ }
+ \end{tabularx}
+
+\end{document}
+