@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c 05.0.00 Development and Testing   - - - - - - - - - - - - - - - - - - - - - -
@c         Structure of test methods and menus   - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Development and Testing
@unnumbered Development and Testing
@cindex 05.0.00
@cindex test methods
@cindex conditional compilation
@cindex compilation, conditional

The methods described in this chapter test all major functionality of the 
AnsiCmd class and the AnsiCmd library as a whole.

These methods are not required for application development, and are therefore 
under a conditional compile directive so they can be disabled in a production 
build. The @t{EarthPoints} test application includes these tests in order to 
demonstrate all AnsiCmd functionality.@*
Please @pxref{Build Options} for more information on conditional 
compilation options.

Each test may be invoked through a command line option. 
@ifnothtml
@*
@end ifnothtml
Please @pxref{Invoking - AnsiCmd Tests} for a list of available options.

The following is a list of the primary test methods found in the 
@t{AnsiCmdTest.cpp} source file.@*
Each method header contains detailed information about that test, and 
exhaustive comments are sprinkled throughout the test code to indicate 
@b{@emph{what}} is being tested, @b{@emph{how}} it is being tested, and 
@b{@emph{why}} it is being tested. These comments should answer most 
questions about the AnsiCmd library, and at the very least, they offer 
an example of how code should be commented.

@ifnothtml
@example
┌─────────────────────────────────────────────────────────────────┐
│ Editorial:                                                      │
│ Many students misunderstand the purpose of comments within the  │
│ source code. Comments DO NOT explain what your code does; the   │
│ the code explains itself.                                       │
│ Rather, comments describe what your code is _intended_ to do.   │
│ That is why comments are (nearly) always written before the     │
│ code itself. Comments explain to _you_ what needs to be done,   │
│ so that after the code is written and fully functional, you can │
│ compare the code with the comments to see if they agree; and    │
│ if not, adjust the one that is incomplete.                      │
│   @EMDASH Software Sam                                                │
└─────────────────────────────────────────────────────────────────┘
@end example
@end ifnothtml
@ifhtml
@indentedblock
@CartHtml{@embedTOKEN{ai}@b{Editorial:}
Many students misunderstand the purpose of comments within the source code.
Comments @i{DO NOT} explain what your code does. Rather, comments describe 
what your code is @b{@i{intended}} to do. That is why comments are (nearly) always 
written before the code itself. Comments explain to @b{@i{you}} what needs to be done, 
so that after the code is written and fully functional, you can compare the code 
with the comments to see if they agree; and if not, adjust the one that is incomplete.
@ @ @EMDASH Software Sam}
@end indentedblock
@end ifhtml

Many of these methods also invoke support methods for user interface duties 
or for various often-used calculations.

Note also that many of these test methods write diagnostic data to the 
debugging log: @b{@t{"dbg.log"}} created in the source code directory.

@anchor{ansiTest_Menu}
@cindex ansiTest_Menu
@itemize @BSQUARE
@item @b{void ansiTest_Menu ( dbgArgs& args );}@*
@ @ @ @ @ @xref{Invoking - AnsiCmd Tests}

This method is called from the application layer by the public method:@*
@ref{ansiTest} which determines whether the conditionally-compiled 
test code is present in the library.

@t{ansiTest_Menu} is the entry point for invoking the individual tests.@*
The command-line arguments are validated and formatted as call parameters, 
and the appropriate test (or test sub-menu) is invoked.

@anchor{Test_4Bit}
@cindex Test_4Bit
@item @b{void Test_4Bit ( void );}@*
@ @ @ @ @ @xref{test C} (f) invocation option.

@anchor{Test_Bg}
@cindex Test_Bg
@item @b{void Test_Bg ( void );}@*
@ @ @ @ @ @xref{test C} (b) invocation option.

@anchor{Test_8bitColor}
@cindex Test_8bitColor
@item @b{void Test_8bitColor ( void );}@*
@ @ @ @ @ @xref{test C} (t) invocation option.

@anchor{Test_RGB}
@cindex Test_RGB
@item @b{void Test_RGB ( wchar_t rgbTest );}@*
@ @ @ @ @ @xref{test C} (r) invocation option.

@anchor{Test_Greyscale}
@cindex Test_Greyscale
@item @b{void Test_Greyscale ( void );}@*
@ @ @ @ @ @xref{test C} (g) invocation option.

@anchor{Test_AixFgBg}
@cindex Test_AixFgBg
@item @b{void Test_AixFgBg ( void );}@*
@ @ @ @ @ @xref{test C} (a) invocation option.

@anchor{Test_acaExpand}
@cindex Test_acaExpand
@item @b{void Test_acaExpand ( void );}@*
@ @ @ @ @ @xref{test C} (d) invocation option.

@anchor{Test_acaExpandSwap}
@cindex Test_acaExpandSwap
@item @b{void Test_acaExpandSwap ( void );}@*
@ @ @ @ @ @xref{test C} (s) invocation option.

@anchor{Test_AltFonts}
@cindex Test_AltFonts
@item @b{void Test_AltFonts ( aeSeq fg );}@*
@ @ @ @ @ @xref{test F} invocation option.

@anchor{Test_CursorPos}
@cindex Test_CursorPos
@item @b{void Test_CursorPos ( aeSeq fg );}@*
@ @ @ @ @ @xref{test P} invocation option.

@anchor{Test_Erasures}
@cindex Test_Erasures
@item @b{void Test_Erasures ( aeSeq fg );}@*
@ @ @ @ @ @xref{test E} invocation option.

@anchor{Test_AsciiCodes}
@cindex Test_AsciiCodes
@item @b{void Test_AsciiCodes ( aeSeq fg );}@*
@ @ @ @ @ @xref{test A} invocation option.

@anchor{Test_Ideogram}
@cindex Test_Ideogram
@item @b{void Test_Ideogram ( aeSeq fg );}@*
@ @ @ @ @ @xref{test @t{I}} invocation option.

@anchor{Test_UnbufferedInput}
@cindex Test_UnbufferedInput
@item @b{void Test_UnbufferedInput ( aeSeq fg );}@*
@ @ @ @ @ @xref{test T} (i) invocation option.

@anchor{Test_TermFlags}
@cindex Test_TermFlags
@item @b{void Test_TermFlags ( aeSeq fg );}@*
@ @ @ @ @ @xref{test T} (t) invocation option.

@anchor{Test_ModFlags}
@cindex Test_ModFlags
@item @b{void Test_ModFlags ( aeSeq fg );}@*
@ @ @ @ @ @xref{test T} (m) invocation option.

@anchor{Test_NonBlock}
@cindex Test_NonBlock
@item @b{void Test_NonBlock ( aeSeq fg );}@*
@ @ @ @ @ @xref{test T} (b) invocation option.

@anchor{Test_RawInput}
@cindex Test_RawInput
@item @b{void Test_RawInput ( aeSeq fg );}@*
@ @ @ @ @ @xref{test T} (r) invocation option.

@anchor{Test_OutputStream}
@cindex Test_OutputStream
@item @b{void Test_OutputStream ( aeSeq fg );}@*
@ @ @ @ @ @xref{test T} (o) invocation option.

@anchor{Test_SoftEcho}
@cindex Test_SoftEcho
@item @b{void Test_SoftEcho ( wchar_t eOpt, aeSeq fg );}@*
@ @ @ @ @ @xref{test T} (e) invocation option.

@anchor{Test_Write}
@cindex Test_Write
@item @b{void Test_Write ( aeSeq fg );}@*
@ @ @ @ @ @xref{test T} (f) invocation option.

@anchor{Test_Window}
@cindex Test_Window
@item @b{void Test_Window ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (w) invocation option.

@anchor{Test_Form}
@cindex Test_Form
@item @b{void Test_Form ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (f) invocation option.

@anchor{Test_Wrap}
@cindex Test_Wrap
@item @b{void Test_Wrap ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (t) invocation option.

@anchor{Test_WinDefault}
@cindex Test_WinDefault
@item @b{void Test_WinDefault ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (d) invocation option.

@anchor{Test_Fifo}
@cindex Test_Fifo
@item @b{void Test_Fifo ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (s) invocation option.

@anchor{Test_Menu}
@cindex Test_Menu
@item @b{void Test_Menu ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (m) invocation option.

@anchor{Test_Hilite}
@cindex Test_Hilite
@item @b{void Test_Hilite ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (h) invocation option.

@anchor{Test_Cookie}
@cindex Test_Cookie
@item @b{void Test_Cookie ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (e) invocation option.

@anchor{Test_Box}
@cindex Test_Box
@item @b{void Test_Box ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (b) invocation option.

@anchor{Test_Line}
@cindex Test_Line
@item @b{void Test_Line ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (l) invocation option.

@anchor{Test_Clip}
@cindex Test_Clipboard_API
@item @b{void Test_Clipboard_API ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (x a) invocation option.

@cindex Test_Clipboard_Win
@item @b{void Test_Clipboard_Win ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (x w) invocation option.

@cindex Test_Tfman
@item @b{void Test_Tfman ( aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (x t) invocation option.

@cindex Test_LaunchExt
@item @b{void Test_LaunchExt ( wchar_t opt, aeSeq fg );}@*
@ @ @ @ @ @xref{test W} (x) invocation option.

@anchor{Test_Dialog}
@cindex Test_Dialog
@item @b{void Test_Dialog ( wchar_t tst );}@*
@ @ @ @ @ @xref{test D} invocation option.

@anchor{Test_Sandbox}
@cindex Test_Sandbox
@item @b{void Test_Sandbox ( wchar_t parmA, wchar_t parmB );}@*
@ @ @ @ @ @xref{test S} invocation option.

This method is provided so that the application developer can write 
experimental code and test it before moving it to the application. 
Because this is an AnsiCmd-class member method, the test code has 
access to all the internal functionality of the library.

@ifnothtml
The Test_Sandbox method is presented here in its entirety.@*
This is the best ride in the amusement park. Have fun!!
@end ifnothtml
@ifhtml
@html
<p style="text-align:center; font-size:1.2em; font-weight:bold;">
The Test_Sandbox method is presented here in its entirety.<br>
This is the best ride in the amusement park. 
<span style=" text-decoration:underline;">Have fun!!</span></p>
@end html
@end ifhtml

@verbatim
void AnsiCmd::Test_Sandbox ( wchar_t parmA, wchar_t parmB )
{
   gString gsOut( "Welcome to the Sandbox!\n" ) ;
   this->ttyWrite ( gsOut ) ;

   //* Create Tests Here... *




   //* --- End of Sandbox Area - Do Not Modify This Line --- **
   this->acSetCursor ( aesCUR_ABSPOS, (this->termRows - 1), 1 ) ;

}  //* End Test_Sandbox() *
@end verbatim
@end itemize
@sp 2


