TIP #452: ADD "STUBS" PACKAGE TO OR ALONG SIDE OF TCLTEST 
===========================================================
 Version:      $Revision: 1.8 $
 Author:       Gerald Lester <Gerald.Lester_at_SAP.com>
               Gerald W. Lester <gerald.lester_at_KnG-Consulting.net>
               Gerald W. Lester <Gerald.Lester_at_gmail.com>
 State:        Draft
 Type:         Project
 Tcl-Version:  8.6
 Vote:         Pending
 Created:      Wednesday, 10 August 2016
 URL:          https://tip.tcl-lang.org452.html
 Post-History: 

-------------------------------------------------------------------------

 ABSTRACT 
==========

 This TIP proposes an enhancement to the *tcltest* package to add 
 support for easy creation of test stubs, mocks and seams. 

 RATIONALE 
===========

 The *tcltest* package allows for automated testing of Tcl code. 
 However, doing proper automated unit testing requires that the unit 
 under test (i.e., the method or procedure) not invoke the actual 
 implementation of other units, but rather should invoke stub or mock 
 units that are under the control of the test being performed as to the 
 results they return and any exceptions they raise. 

 This TIP adds support for building these mechanisms, making it 
 significantly easier to create isolated unit tests of Tcl code. 

 PROPOSAL 
==========

 That a framework to easily create test stubs/mocks of Tcl commands be 
 added to the *tcltest/ package. Additionally, to facilitate the 
 creation of automated test for legacy Tcl code. Commands supporting 
 /test seam/ creation and specification would also be included proposed 
 package. 

 DESCRIPTION 
-------------

 It provides a fully functional implementation of the following 
 commands: 

     * *::tcltest::TestSetup* - Defines which procedures/commands are 
       stubbed out and how they should behave for each invocation. This 
       should only be called once per test. 

     * *::tcltest::AddStub* - Adds a procedures/commands to the list 
       that are stubbed out. 

     * *::tcltest::SaveVars* - Saves the values of variables to be 
       restored later. This should only be called once per test. 

     * *::tcltest::AddVars* - Add a variable to the list of variables to 
       be restored later 

     * *::tcltest::CallCount* - Returns a dictionary sorted list of the 
       stubbed out procedures and how many times they were called. 

     * *::tcltest::TestCleanup* - Restores saved variables and stubbed 
       out procedures. 

     * *::tcltest::SortedArrayData* - Return the values of an array as a 
       list of key-value pairs sorted by the keys. 

     * *::tcltest::CallProc* - Call the real implementation of a stubbed 
       out procedure. 

     * *::tcltest::Seam* - Test seam definition and injection (aka 
       enabling). This command is available without requiring the 
       tcltest package.  

 REFERENCE IMPLEMENTATION 
==========================

 See the tip-452 branch 
 (<URL:http://core.tcl.tk/tcl/timeline?n=100&r=tip-452>), in particular, 
 see http-tip-452.test for an example of using the procedures added by 
 this package. 

 ORIGINS OF REFERENCE IMPLEMENTATION 
-------------------------------------

 The reference implementation was done at SAP Labs, LLC (a subsidiary of 
 SAP Americal, Inc.) and approved for release as Open Source under a BSD 
 license. 

 COPYRIGHT 
===========

 This document has been placed in the public domain. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows