From 6898cb4397493963bc00d7473c7515283fc0ec23 Mon Sep 17 00:00:00 2001 From: shmibs Date: Sat, 19 Dec 2015 01:39:36 -0700 Subject: restructure file layout --- doc/a_simple_example.c | 52 +++++++++++++ doc/usage.pdf | Bin 0 -> 138351 bytes doc/usage.tex | 207 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 259 insertions(+) create mode 100644 doc/a_simple_example.c create mode 100644 doc/usage.pdf create mode 100644 doc/usage.tex (limited to 'doc') 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 Binary files /dev/null and b/doc/usage.pdf 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} + -- cgit v1.2.3