%\VignetteDepends{}
%\VignetteIndexEntry{Building Packages-Exercises}
%\VignettePackage{AdvancedR}

\documentclass{article}

\usepackage[colorlinks=true,linkcolor=blue]{hyperref}
\usepackage{theorem}
\usepackage{underscore}
\usepackage{color}

\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Rmethod}[1]{{\texttt{#1}}}
\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textsf{#1}}}
\newcommand{\Rfunarg}[1]{{\texttt{#1}}}
\newcommand{\Rclass}[1]{{\textit{#1}}}

\newcommand{\code}[1]{{\texttt{#1}}}
\newcommand{\file}[1]{{\texttt{#1}}}

\newcommand{\software}[1]{\textsf{#1}}
\newcommand{\R}{\software{R}}
\newcommand{\bioc}{\software{BioConductor}}

%% Excercises and Questions
\theoremstyle{break} \newtheorem{Ex}{Exercise}
\theoremstyle{break} \newtheorem{Q}{Question}
%% And solution or answer
\newenvironment{solution}{\color{blue}}{\bigskip}

\begin{document}

\SweaveOpts{keep.source=TRUE,width=9,height=8,eps=FALSE,include=FALSE,prefix.string=niFig}

\title{Buillding packages: Self-Study Exercises}
\author{Chao-Jen Wong, Nishant Gopalakrishnan}
\date{20 May, 2010}
\maketitle

%% \tableofcontents

<<setup, echo=FALSE>>=
options(width=60)
@

The \Rpackage{AdvancedR} package contains the sources of the
\Rpackage{nidemo} package. The exercises below will take the \Rpackage{nidemo}
package code as a starting point, so you will want to have the source
for this package at hand. If you have installed the \Rpackage{AdvancedR} 
pacakge, you can find the sources for \Rpackage{nidemo} as follows:

<<findingnidemo>>=
system.file("packages", package = "AdvancedR")
@

The main goal of this excercise is to learn how to add unit tests to the
\Rpackage{nidemo} package, by making use of the unit testing framework provided
by the \Rpackage{RUnit} package. 

In the following excercises, we will be creating unit tests for two functions 
\Rfunction{alpha\_freq\_R} and \Rfunction{demo_which} from the 
\Rpackage{nidemo} package. The \Rfunction{alpha\_freq\_R} function returns a
named array containing the number of occurances of each character in a given file.
The \Rfunction{demo_which} function returns the \Robject{TRUE} indices of a 
logical vector.

\begin{Ex}
Build and install the \Rpackage{nidemo} package and test out both
\Rfunction{alpha\_freq\_R} and \Rfunction{demo_which} functions.
\end{Ex}

\begin{Ex}
Create unit tests for functions \Rfunction{alpha\_freq\_R} and 
\Rfunction{demo_which} and save them to the inst/unitTests 
folder of the \Rpackage{nidemo} package.

\noindent Hint: write tests that check for\ldots
\begin{itemize}
\item Correctness of output
\item Exception conditions
\end{itemize}
Hint:
\begin{itemize}
\item \Rpackage{RUnit} relies on file naming conventions; place your
  tests in files whose names match the pattern \verb|".+_test\\.R$"|
\item \Rpackage{RUnit} relies on function naming conventions; each
  unit test function should match \verb|"^test.+"|. Each test should
  be a function with no arguments.
\end{itemize}
\end{Ex}

The \Rfunction{writeRUnitRunner} creates a \Rfunction{.test} function that makes
use of functions from the \Rpackage{RUnit} package to create a test suite, run
the test suite and summarize results.
\begin{Ex}
\begin{itemize}
\item Since we are making use of functions from the \Rpackage{RUnit} package,
 add \Rpackage{RUnit} to the Suggests field of the DESCRIPTION file.
\item Create a \Rfunction{.test} function that runs all the unit tests for 
\Rpackage{nidemo} using the \Rfunction{writeRUnitRunner} function and save it
to the R folder of the \Rpackage{nidemo} package.
\end{itemize}
\end{Ex}


\begin{Ex}
Create an R script in the tests folder of the \Rpackage{nidemo} package
that calls the \Rfunction{.test} function.\\
Hint:
\Rfunction{.test} is not exported from the \Rpackage{nidemo} package. Use \Rfunction{:::}
\end{Ex}

\begin{Ex}
Run R CMD check and verfiy that the \Rpackage{nidemo} passes all the unit tests.
\end{Ex}
\end{document}
