\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#452: Add "stubs" Package to or Along Side of TclTest}
\date{August 10, 2016}
\author{Gerald Lester, Gerald W. Lester, Gerald W. Lester}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#452}&\textbf{Add "stubs" Package to or Along Side of TclTest}\\\hline
Author&

Gerald Lester \tipmail{Gerald.Lester}{SAP.com}
\par
Gerald W. Lester \tipmail{gerald.lester}{KnG-Consulting.net}
\par
Gerald W. Lester \tipmail{Gerald.Lester}{gmail.com}
\\
Created&Wednesday, \(\text{10}^{\text{th}}\) August 2016\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.8 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes an enhancement to the \textbf{tcltest} package to add support for easy creation of test stubs, mocks and seams.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The \textbf{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.

\section{Proposal}

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

\subsection{Description}

It provides a fully functional implementation of the following commands:
\begin{itemize}
\item{}
\textbf{::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.
\item{}
\textbf{::tcltest::AddStub} --- Adds a procedures/commands to the list that are stubbed out.
\item{}
\textbf{::tcltest::SaveVars} --- Saves the values of variables to be restored later. This should only be called once per test.
\item{}
\textbf{::tcltest::AddVars} --- Add a variable to the list of variables to be restored later
\item{}
\textbf{::tcltest::CallCount} --- Returns a dictionary sorted list of the stubbed out procedures and how many times they were called.
\item{}
\textbf{::tcltest::TestCleanup} --- Restores saved variables and stubbed out procedures.
\item{}
\textbf{::tcltest::SortedArrayData} --- Return the values of an array as a list of key-value pairs sorted by the keys.
\item{}
\textbf{::tcltest::CallProc} --- Call the real implementation of a stubbed out procedure.
\item{}
\textbf{::tcltest::Seam} --- Test seam definition and injection (aka enabling). This command is available without requiring the tcltest package. 
\end{itemize}

\section{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.

\subsection{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.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
