diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/a_simple_example.c | 52 | ||||
| -rw-r--r-- | doc/usage.pdf | bin | 0 -> 138351 bytes | |||
| -rw-r--r-- | doc/usage.tex | 207 |
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 Binary files differnew file mode 100644 index 0000000..fb6f9c7 --- /dev/null +++ b/doc/usage.pdf 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} + |