aboutsummaryrefslogtreecommitdiffstats
path: root/longbow/documentation/LaTeX Documentation/Document.tex
blob: 273336ef0b8d9a51c09e8b5141c275ef8b8ebe49 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
\begin{document}

\flushbottom % Makes all text pages the same height

\maketitle % Print the title and abstract box

% Use the multicols package to a make multi-column table of contents.
\begin{multicols}{2}
\tableofcontents
\end{multicols}

%For a single column table of contents just use this
%\tableofcontents % Print the contents section

\thispagestyle{empty} % Removes page numbering from the first page

%\newcommand{\HRule}{\rule{\linewidth}{0.5mm}} % Defines a new command for the horizontal lines, change thickness here

\section{Overview} % The \section{} command stops section numbering

LongBow is software to help you write better C programs. It provides: 
\begin{itemize}
\item A run-time assertion facility to establish strict rules on the state of your program.
\item A testing facility based on the xUnit testing model.
\item Compile-time assistance for writing code meant to be compiled by compilers with different features. 
\end{itemize}

LongBow can help you find and manage problems early, establish and maintain confidence in the correctness of your code, make collaboration easier, facilitate future change, and improve overall design.

LongBow allows you to take control and establish invariant pre- and post-conditions that detect inconsistencies and unexpected results in your programs in order to find bugs and design deficiencies in the code during development rather than waiting for others to find your bugs for you.

\section{Set up and installation} 
How to install, configure, link, and run LongBow.

\subsection {Installation}
Get the tar file from xxx.
untar and do a make install.
The resulting LongBow directory will contain the C header files, C source files, and runtime libraries needed.

\subsection {Configuration}

\subsubsection{LongBow with LLDB}
The {\tt lldb} debugger is aware when C source files (not header files) are included in another source file.
This induces a problem where the breakpoints in the included source files are not set.
But you can configure lldb to set them: In the file {\tt \~/.lldbinit},
add the line:
 
\begin{lstlisting}
settings set target.inline-breakpoint-strategy always
process handle -p true -s false SIGABRT
\end{lstlisting}

\subsubsection{LongBow with GDB}
LongBow uses signals to interrupt program flow when an assertion fails.
When using gdb this will cause gdb to stop running of the test.
This probably isn't what you want and would rather prefer that gdb just
ignore the signal and let the LongBow unit test signal handler take care of the signal.
To do this, you must configure gdb to ignore the signal and to allow it to pass to the program being executed.
In the file {\tt \~/.gdbinit}, add the line:
 
\begin{lstlisting}
handle 6 nostop pass
\end{lstlisting}

\subsubsection{Linking and Libraries}
There are two LongBow libraries that must be linked with the application: the primary LongBow library, (\url{liblongbow.a}) and one of the LongBow reporter libraries.
The reporter libraries enable the reporting mechanism for Longbow.
Currently two reporter libraries have been implemented:
\begin{enumerate}
\item \url{liblongbow-plaintext.a} which displays output as simple text; and
\item \url{liblongbow-ansiterm.a} which displays output as an ANSI colorized output.
\end{enumerate}

Both display to standard output.

\subsubsection{Running and Runtime Behavior}
You can "run" Longbow in one of two ways: you can run your application with assertions turned on in order to test expected invariance during runtime; or you can run your tests using Longbow's Test Runner.
Turning off assertions for runtime is not currently supported.
 
\section{Programming with Assertions} 

Longbow's  Assertions offer a way to check runtime invariance throughout your program.
Traps are a subset of Assertions that are executed at runtime even if Assertions have been turned off during deployment. They should be used when program failure is the correct response to assertion failure.
 
The assertion framework is based on the following design principles:
\begin{itemize}
\item  It is intentionally simple and can be extended.
\item  You don't have to change your program design to accommodate assertions.
\item  It is designed specifically for C programs.
\item  It is based on programming with invariance.
\item  Assertions may be used only during development as a debugging aid, or in deployment as well to offer more descriptive errors to users.
\end{itemize}


\subsection{Designing with Assertions }
Assertions can be used to debug code and give better information about errors to users.
They should not be used for error handling.
Assertions should be used to explicitly test for conditions that must be true in order for an operation to work. Examples include testing for NULL pointers, out-of-bounds array indices, and incorrect dependent relationships. Ultimately your code should work every time under all input conditions without ever triggering an assertion although passing tests don't guarantee proper design. You should aim for 100\% code coverage.

Be strategic about where the assertions are located and what they test for.
A failed assertion should be considered a bug should be treated as such.
For example a failure to open a file is likely not a bug in your program, per se, but indicative of some other problem and programmatic error handling would probably be the best approach to handling the missing file.

Assertions can be included or excluded at compile-time. In many cases, it is reasonable to keep the assertions in production releases as an aid to future bug reporting.
  
\subsection{Using the Assertion Libraries }  

LongBow provides a basic set of assertions that test a condition and trigger the assertion if the condition fails to be true. When an assertion triggers the following occurs:
\begin{itemize}
\item An Event is created which records the kind of assertion that failed and the location of the assertion's failure.
\item The formatted message of the failed assertion is reported via the LongBow report library.
\item The running program is sent a {\tt SIGABRT} signal.
\end{itemize}

The following four assertions are currently supported:
\begin{itemize}
\item {\tt assertTrue}
\item {\tt assertFalse}
\item {\tt assertNull}
\item {\ttfamily assertNotNull}
\end{itemize}

The function signatures for assertions follow the pattern:

\Cfunctiondef{\tt void}{assertX}{{\it condition}, {\tt "message", ...}}

Where {\tt "message"} is a printf(3) format, nul-terminated C-String that will be displayed when the assertion triggers.  The ... represents the arguments that might be used to create the string.

There is one C header file that must be required to use the assertion mechanism:
\begin{itemize}
\item \textbf{LongBow/runtime.h} is the basic header file needed for assertions.
\end{itemize} 

\subsection {Using Traps}
LongBow traps are subsets of assertions and are intended for simple error reporting.
There is no functional difference between a trap and an assertion, however, a traps cannot be shut off during runtime so they are good to use for deployment if you plan to turn assertions off and the program should terminate when the assertion is not met.

Traps take as arguments a condition and a printf(3) format C string of explanatory text along with any values necessary to format the string.

A typical trap function signature is:

\Cfunctiondef{\tt void}{trap{\it Kind}}{{\it condition}, {\tt "message", ...}}

Where {\it Kind} represents the kind of trap (see {\tt LongBow/traps.h}.
If the {\it condition} is evaluated to {\tt true}, the trap is triggered.

where {\tt ...} is the printf format string and values.

\noindent Currently supported traps are defined in \texttt{traps.h} and include:
\begin{itemize}
\item  \textbf{trapIllegalValue:} Used for capturing failed parameter validation, for example.
\item  \textbf{trapIllegalValueIf:} Used to trap an illegal value if a condition is met.
\item  \textbf{trapNotImplemented:} Used to report and abort an unimplemented capability.
\item  \textbf{trapOutOfBounds:}  Used to trap an out-of-bounds condition on an index.
\item  \textbf{trapOutOfBoundsIf:} Used to trap an out-of-bounds condition for a specific value.
\item  \textbf{trapOutOfMemory:} Used to signal that no more memory can be allocated.
\item  \textbf{trapUnexpectedState:} Used to signal that an unexpected or inconsistent state was encountered.
\item  \textbf{trapUnexpectedStateIf:} If the given condition is true, used to signal that an unexpected state was encountered.
\item  \textbf{trapUnrecoverableState:} Used to report an unrecoverable state in program execution.
\end{itemize}

\subsection{Examples }  

\paragraph {assertNotNull example}

\begin{lstlisting}
#include <LongBow/assertions>
#include <unistd.h>
#include <string.h>

void
function(char *pointer)
{
    assertNotNull(pointer, "The pointer cannot be NULL.");

    write(1, pointer, strlen(pointer));
}

int
main(int argc, char *argv[])
{
    function(0);
}
\end{lstlisting}


In this case the {\tt assertNotNull} will trigger and the program will immediately terminate with the following output:

\begin{lstlisting}
Assert pointer.c:8 function() pointer != NULL The pointer cannot be NULL.
0   pointer                 0x0000000107840d4c function + 188
1   pointer                 0x0000000107840dd1 main + 33
2   libdyld.dylib           0x00007fff887595fd start + 1

\end{lstlisting}

\paragraph {assertTrue example}

\begin{lstlisting}
LONGBOW_TEST_CASE(Global, myTest)
{
    struct timeval timeval;
    timeval.tv_sec = 0;
    timeval.tv_usec = 1000;
    
    char *expected = "0.001000";
    char *actual = parcTime\_FormatTimeval(timeval);
    assertTrue(strcmp(expected, actual) == 0, "Expected \%s, actual \%s", expected, actual);
    parc_free(actual);
}
 \end{lstlisting}
 
\paragraph{Example using assertNull, assertNotNull, and assertTrue}
 
\begin{lstlisting}
static void
parcDeque_AssertInvariants(const PARCDeque *deque)
{
    assertNotNull(deque, "Parameter cannot be null.");
    if (deque->head != NULL) {
        assertTrue(deque->size != 0, "PARCDeque head is not-null, but size is zero.");
        assertNotNull(deque->tail, "PARCDeque head is not-null, but tail is null.");
        parcDequeNode_AssertInvariants(deque->head);
        parcDequeNode_AssertInvariants(deque->tail);
    } else {
        assertNull(deque->tail, "PARCDeque head is null, but tail is not null.");
        assertTrue(deque->size == 0, "PARCDeque head is null, but size is not zero.");
    }
}

\end{lstlisting}

\paragraph {assertFalse example}
\begin{lstlisting}
RtaCommand *
rtaCommand_Read(int fd)
{
    ssize_t readlen;
    uint32_t netbyteorder;
    size_t len;
    char *p;
    RtaCommand *command;

    readlen = read(fd, &netbyteorder, 4);
    assertFalse(readlen < 0, "socket read error: \%s\n", strerror(errno));
    assertTrue(readlen == 4, "Partial read on command length");

    len = ntohl(netbyteorder);
    p = parc_malloc(len);
    readlen = read(fd, p, len);
    assertTrue(readlen == len, "Partial read on command");

    command = rtaCommand_Parse(p);
    parc_free(p);
    return command;
}
\end{lstlisting}


\section{Unit testing}  
Longbow provides an xUnit-style unit testing framework. The framework is a mechanism for organizing and running trees of test code. It is organized hierarchically into three components: a Test Runner, Test Fixtures, and Test Cases.

A Test Runner file is associated 1:1 with a C source file, with the word "test\_" prepended on the C source file name.  For example, the Test Runner file for {\tt parc\_Buffer.c} would be {\tt test\_parc\_Buffer.c}.
This file contains all of the Test Fixtures and Test Cases needed to test the associated C source file.

Each Test Runner will run a set of Test Fixtures.
Test Fixtures are an organizational unit that allows you to group your Test Cases.
The grouping may be done by functionality, by static vs non static functions, or by any other organizing principle that you choose. 
 
A Test Fixture runs a set of Test Cases each of which is responsible for testing some aspect of the C module. 

Tests are run in the order they are defined.
The Test Runner will start with Test Fixture1 and all of its Test Cases, move on to Test Fixture2 and its Test Cases etc. Tests should be idempotent, however, and not assume any particular order or be dependent on each other.
They should not leave state such that the next Test Case inherits that state. 

%\subsection{Designing tests }  
%\textcolor{red}{Put something here}

\subsection{Writing tests with the Test Runner module }  
\subsubsection{Test Runners}
A Test Runner is the top-level executable unit in a test.
It is responsible for establishing the necessary state for the set of tests it contains, executing the tests via Test Fixtures and Test Cases, and tearing down state when the tests have completed. 

A Test Runner requires the  following header files:
\begin{itemize}
\item \textbf{LongBow/runtime.h} is the basic header file needed for assertions and testing.
\item \textbf{LongBow/unit-test.h} is the basic header file needed for testing.
\item \textbf{LongBow/compiling.h} is used when you have code that needs to work across multiple compilers - it contains the matrix of compiler and / you are using.
\end{itemize} 

\noindent The source code of a Test Runner has the following basic structure:

\begin{lstlisting}
#include <LongBow/testing.h>

LONGBOW_TEST_RUNNER(myRunner)
{
}

LONGBOW_TEST_RUNNER_SETUP(myRunner)
{
    // Code to set up required state
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_RUNNER_TEARDOWN(myRunner)
{
    //Code to clean up state
    return LONGBOW_STATUS_SUCCEEDED;
}

\end{lstlisting}


Each of these functions has a local variable - {\tt LongBowRunner *testRunner} - which may be used to manipulate the clipboard (as an example).  The Text Fixtures and Test Cases launched by the Test Runner will have access to this variable as well as their own local variable.  Thus a Test Fixture will have access to the {\tt  testRunner} that is passed to it as well as its own {\tt LongBowFixture *testFixture} and a Test Case will have access to {\tt testRunner, testFixture} and its own {\tt LongBowCase *testCase}.

\subsubsection{Test Fixtures}

A Test Fixture is a subcomponent which has the same structure as a Test Runner.
The following code adds Test Fixture to a Test Runner:

\begin{lstlisting}
LONGBOW_TEST_RUNNER(myRunner)
{
    LONGBOW_RUN_TEST_FIXTURE(Global);
    LONGBOW_RUN_TEST_FIXTURE(Local);
}
\end{lstlisting}


Like the Test Runner, it is responsible for setting up and tearing down state needed by the Test Cases.   

\begin{lstlisting}
 
LONGBOW_TEST_FIXTURE(Global)
{
    LONGBOW_RUN_TEST_CASE(Global, myTest);
}

LONGBOW_TEST_FIXTURE_SETUP(Global)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_FIXTURE_TEARDOWN(Global)
{
    return LONGBOW_STATUS_SUCCEEDED;
}
\end{lstlisting}

\subsubsection{Test Cases}
Test Cases are the leaf nodes of the testing tree.  Each Test Case tests one aspect of the C module.

\paragraph {Handling Test Case state safely}

Every Test Case has access to a private \"clipboard\" that contains data shared between the Test Case and the set up and teardown functions of its encapsulating Test Fixture.
This shared state is used to provide specific environment or initialized variables for the test and for the test to communicate specialized information to the teardown function.

For example, a Test Case which is expected to fail as the result of testing a failure condition might exit without releasing resources which are left in an unsafe state.
As multiple tests may be run in one process, it is important to clean these up before launching the next test.

The following example demonstrates the clipboard mechanism: 
\begin{itemize}
\item{The Test Fixture setup function allocates the necessary resources and puts references to them into the clipboard.}
\item{The Test Case gets these references, uses them, and fails.} 
\item{The Test Fixture tear-down function obtains the resources from the clipboard and deallocates them.}
\end{itemize}

\subsubsection {Test Runner Example}
The following is an example of a test file :

\begin{lstlisting}
#include <stdio.h>
#include <string.h>

#include <LongBow/testing.h>
#include <LongBow/debugging.h>

LONGBOW_TEST_RUNNER(testClipboard)
{
    LONGBOW_RUN_TEST_FIXTURE(Global);
}

LONGBOW_TEST_RUNNER_SETUP(testClipboard)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_RUNNER_TEARDOWN(testClipboard)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_FIXTURE(Global)
{
    LONGBOW_RUN_TEST_CASE(Global, testClipboard);
}

LONGBOW_TEST_FIXTURE_SETUP(Global)
{
    char *testData = strdup("Hello World");
    longBowTest Case_SetClipBoardData(testCase, testData, free);
    
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_FIXTURE_TEARDOWN(Global)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_CASE(Global, testClipboard)
{
    char *testData = longBowTest Case_GetClipBoardData(testCase);
    printf("Shared state '%s'\n", testData);
}

int
main(int argc, char *argv[])
{
    LongBowRunner *testRunner = LONGBOW_TEST_RUNNER_CREATE(testClipboard);
    int exitStatus = LONGBOW_TEST_MAIN(argc, argv, testRunner);
    longBowTest Runner_Destroy(&testRunner);
    exit(exitStatus);
}
\end{lstlisting}

\subsubsection {Testing for Successful Failure}
Testing for success is straightforward but we also may have to test that something fails when it is supposed to. 
This section describes how to test for an expected non-success result.

To compose a Test Case that expects a result other than success, use the {\tt LONGBOW\_TEST\_CASE\_EXPECTS} function which takes the expected event as a parameter and completes.  The example below shows the capture of a successful segmentation fault.
  

\begin{lstlisting}
#include <stdio.h>
#include <sys/types.h>
#include <signal.h>

#include <LongBow/unit-test.h>

LONGBOW_TEST_RUNNER(LongBow)
{
	LONGBOW_RUN_TEST_FIXTURE(MyFixture);
}

LONGBOW_TEST_RUNNER_SETUP(LongBow)
{
	return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_RUNNER_TEARDOWN(LongBow)
{
	return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_FIXTURE(MyFixture)
{
	LONGBOW_RUN_TEST_CASE(MyFixture, alwaysSEGV);
}

LONGBOW_TEST_FIXTURE_SETUP(MyFixture)
{
	return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_FIXTURE_TEARDOWN(MyFixture)
{
	return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_CASE_EXPECTS(MyFixture, alwaysSEGV, .event = &LongBowEventSIGSEGV)
{
	int *p = 0;
	int i = *p;
}

int
main(int argc, char *argv[])
{
	LongBowRunner *testRunner = LONGBOW_TEST_RUNNER_CREATE(LongBow);
	int status = LONGBOW_TEST_MAIN(argc, argv, testRunner, NULL);
	longBowTest Runner_Destroy(&testRunner);

	exit(status);
}

\end{lstlisting}

\subsection{Running tests}  

The overall process for writing and running your tests:
\begin{itemize}
\item  Write a Test Runner file for every .c file that completely tests all of the code container in the .c file. This filename should be "test\_" prepended to the name of the file you are testing.
\item  Compile the Test Runner file with one of:
\begin {itemize}
\item  -llongbow -llongbow-ansiterm
\item  -llongbow -llongbow-textplain
\end{itemize}
\item  Execute the Test Runner.
\end{itemize}


\subsection{Examples }  

Here is an example of a C source file and its associated Test file.  Tutorial.c is a small C program which simply  provides an uninteresting but useful exemplar of the test framework.


\noindent \textbf{Tutorial.c}

\begin{lstlisting}
#include <unistd.h>
#include <stdbool.h>
#include <signal.h>

static bool
_privateFunction()
{
    return true;
}

bool
alwaysSucceed()
{
	return _privateFunction();
}

bool
alwaysFail()
{
	return false;
}

bool
blowUp()
{
    char *p = 0;
    *p = 0;
    
    return true;
}

\end{lstlisting}

The following code is the test file for the Tutorial.c.  Note that the file name is simply the C source file name with "test\_" prepended. In this example, the Test Runner divides the Test Cases into two Test Fixtures: one to focus on the Static functions and one to focus on the Global functions.

\noindent \textbf{test\_Tutorial.c}
\begin{lstlisting}

#include "tutorial.c"

#include <LongBow/unit-test.h>


LONGBOW_TEST_RUNNER(myTutorialTest)
{
    LONGBOW_RUN_TEST_FIXTURE(Static);
    LONGBOW_RUN_TEST_FIXTURE(Global);
}

LONGBOW_TEST_RUNNER_SETUP(myTutorialTest)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_RUNNER_TEARDOWN(myTutorialTest)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_FIXTURE(Global)
{
    LONGBOW_RUN_TEST_CASE(Global, alwaysSucceed);
    LONGBOW_RUN_TEST_CASE(Global, alwaysFail);
    LONGBOW_RUN_TEST_CASE(Global, blowUp);
    
}

LONGBOW_TEST_FIXTURE_SETUP(Global)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_FIXTURE_TEARDOWN(Global)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_CASE(Global, alwaysSucceed)
{
    bool result = alwaysSucceed();
    
	assertTrue(result, "This test must always succeed.");
}

LONGBOW_TEST_CASE(Global, alwaysFail)
{
    bool result = alwaysFail();
    
	assertTrue(result, "This test will fail.");
}

LONGBOW_TEST_CASE_EXPECTS(Global, blowUp, .event = &LongBowEventSIGSEGV)
{
    blowUp();

    assertTrue(false, "This will not be executed");
}


LONGBOW_TEST_FIXTURE(Static)
{
    LONGBOW_RUN_TEST_CASE(Static, _privateFunction);
}

LONGBOW_TEST_FIXTURE_SETUP(Static)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_FIXTURE_TEARDOWN(Static)
{
    return LONGBOW_STATUS_SUCCEEDED;
}

LONGBOW_TEST_CASE(Static, _privateFunction)
{
    bool result = _privateFunction();
    
	assertTrue(result, "This test must always succeed.");
}

int
main(int argc, char *argv[argc])
{
    LongBowRunner *testRunner = LONGBOW_TEST_RUNNER_CREATE(myTutorialTest);
    int status = LONGBOW_TEST_MAIN(argc, argv, testRunner);
    
    longBowTest Runner_Destroy(&testRunner);
    exit(status);
}

\end{lstlisting}

\section {Compiling and Compiler Support}
LongBow consolidates a variety of compile-time options that you include in your code.

For example, the C99 standard defines the pragma operator and various compilers support this in various ways.

\section{The LongBow Reporter}  
The Longbow reporter offers a more user-friendly option for viewing the output of the running tests. In addition to linking with the primary LongBow library ({\tt liblongbow.a}), you also need to link with one of the following reporting libraries to control presentation of the test output.
\begin{itemize}
\item {\bf liblongbow-ansiterm.a} This option produces output that is color coded to indicate the degree of success: green for a successful test; yellow for warnings; and red for failure.
\item {\bf liblongbow-plaintext.a} This option produces plain text output.
\item {\bf liblongbow-json.a} This option is in development and will produce output in JSON format.
\end{itemize}



\section {Appendices}
\subsection {Function Documentation}
The following modules are included in LongBow:
\begin {itemize}
\item \textbf{Runtime:}	LongBow functions and macros for runtime.
\item \textbf{Testing:}	 LongBow functions and macros for writing tests.
\item \textbf{Internals:} LongBow functions and macros used internally.
\item \textbf{Reporting:}	LongBow functions and definitions for writing report libraries.
\item \textbf{Performance testing:} LongBow functions and definitions for writing performance tests.
\end{itemize}

\paragraph {Runtime}
LongBow runtime support consists primarily of assertions and traps. Developers insert assertions to insist that certain conditions are true before permitting the program to continue. If the assertion fails, the program is abnormally terminated. It uses the following files:

\begin{itemize}
\item {\bf assertions.h:} 	Runtime and Test Assertions.
 \item {\bf longBow\_EventType.h:} LongBow Events and Support. 
 \item {\bf longBow\_Runtime.h:} The LongBow Runtime support. 
 \item {\bf runtime.h:} LongBow Runtime Support. 
 \item {\bf traps.h:} Runtime and Test Traps. 
\end{itemize}


\paragraph {Testing}
LongBow testing support consists of macros and ancillary functions to implement an xUnit style of writing and running tests. Test writers create a LONGBOW\_TEST\_RUNNER function which invokes one or more LONGBOW\_TEST\_FIXTURE functions, each of which invoke a specific LONGBOW\_TEST\_CASE. It uses the following files:

\begin{itemize}
\item {\bf longBow\_EventType.h:} 	LongBow Events and Support. 
 \item {\bf longBow\_Main.h:} A main() function to run one or more LongBow Test Runners. 
 \item {\bf longBow\_OpenFile.h:} LongBow support for files and file descriptors. 
 \item {\bf longBow\_Runner.h:} LongBow Test Runner Support. 
 \item {\bf longBow\_Status.h} A simple status representation for a LongBow Test Case. 
  \item {\bf longBow\_Test CaseClipBoard.h:} LongBow Clipboard shared between the setup, test case, and teardown. 
 \item {\bf longBow\_UnitTesting.h} Unit Testing Support. . 
 \item {\bf testing.h:} LongBow testing functionality. 
 \item {\bf unit-test.h} LongBow Unit Test Support. 
\end{itemize}

\paragraph {Internals}
LongBow functions and macros used internally.
It uses the following files:

\begin{itemize}
 \item {\bf longBow\_ArrayList.h} A simple, list implementation using a dynamic array.  
 \item {\bf longBow\_Backtrace.h} Support for Stack Traces. 
 \item {\bf longBow\_Configuration.h} Support for LongBow Configuration. 
 \item {\bf longBow\_Debugging.h} Support for LongBow and Application Debugging. 
 \item {\bf longBow\_Event.h} LongBow Event Support. 
 \item {\bf longBow\_EventType.h} LongBow Events and Support. 
 \item {\bf longBow\_Fixture.h} Manage the execution of Test Cases. 
 \item {\bf longBow\_Location.h} LongBow Source File Location. 
 \item {\bf longBow\_Test Case.h} The interface and supporting functionality of a LongBow Test Case. 
 \item {\bf longBow\_Test CaseResult.h} LongBow Test Case Results. 
\end{itemize}
 
 
 \paragraph {Reporting}
LongBow functions and definitions for writing report libraries.  
It uses the following header files:

\begin{itemize}
 \item {\bf longBow\_ReportANSITerminal\_Runtime.h} ANSI Terminal Reporting.  
\item {\bf longBow\_Report\_Runtime.h} The LongBow Runtime Report Generator.  
\item {\bf longBow\_Report\_Testing.h} The LongBow Test Report Generator. 
\end{itemize}

 	
 \paragraph {Performance Testing}
Using LongBow for performance tests.

\end{document}