Verified Commit 84dc5f6e authored by Camil Staps's avatar Camil Staps 🚀

Start writing documentation (clean-test#15)

parent b9586b80
Pipeline #13816 failed with stage
in 48 seconds
clean-compiler/
*.abc
*.o
*.prj
*.aux
*.fdb_latexmk
*.fls
*.log
*.out
*.pdf
*.toc
clean-compiler/
testproperties
\documentclass[a4paper]{article}
\usepackage{geometry}
\usepackage[hidelinks]{hyperref}
\usepackage[british]{babel}
\usepackage{latexgit}
\usepackage{fancyvrb}
\usepackage{cleveref}
\usepackage{enumitem}
\setlist{itemsep=0pt}
\title{clean-test-properties: documentation}
\author{Camil Staps}
\date{\gitcommitdate[formatDate]}
\begin{document}
\maketitle
\begin{abstract}
Clean-test-properties is a tool for automated testing of Clean libraries.
It collects Gast properties from definition modules and automatically generates test modules for them.
\end{abstract}
\tableofcontents
\input{installation}
\input{usage}
\end{document}
\section{Installation}
Clean-test-properties is not yet included in any distribution, so you have to build the tool yourself.
On Linux and Mac, you can clone the repository and run \verb$make$ to fetch dependencies and build the binary.
\begin{Verbatim}[fontsize=\small]
git clone https://gitlab.science.ru.nl/clean-and-itasks/clean-test-properties
cd clean-test-properties
make
\end{Verbatim}
\section{Usage}
For a list of all command line arguments, run \verb$testproperties --help$.
This documentation discusses the most common use cases.
General options are \verb$--verbose$ (\verb$-v$) for more verbose output,
\verb$--quiet$ (\verb$-q$) for less verbose output,
and \verb$--no-color$ for output without ANSI escape sequences for colors.
The verbosity options (\verb$-v$ and \verb$-q$) may be given multiple times.
The typical workflow followed by \verb$testproperties$ is:
\begin{enumerate}
\item Find modules to test.
\item Find properties.
\item Generate test modules.
\item Compile test modules.
\item Run test modules.
\end{enumerate}
\subsection{Find modules to test}
By default, \verb$testproperties$ recursively searches all definition modules in the current directory for properties.
Use \verb$--directory$ (\verb$-d$) to specify a different directory.
Use \verb$--module$ (\verb$-m$) to only search a specific module.
This option can be given multiple times.
\subsection{Find properties}
Ways to specify properties are described in \cref{sec:specifying-properties}.
There are no options relating to this step.
\subsection{Generate test modules}
For each module, a new module is generated with the same name and a prefix.
The prefix can be set with \verb$--prefix$ (\verb$-p$; default \verb$_Tests$).
For instance, by default the tests for \verb$Data.Set$ appear in \verb$_Tests.Data.Set$.
By default, tests are generated in the current directory (e.g., \verb$./_Tests/Data/Set.icl$).
Use \verb$--output-directory$ (\verb$-D$) to set a different directory.
The generated module uses \verb$exposeProperties$ from \verb$Gast.CommandLine$.
This means the test module has a standard command line interface to set test and output options.
The default options can be set with \verb$--print-option$ (\verb$-P$) and \verb$--test-option$ (\verb$-T$).
For instance, use \verb$--test-option 'Tests 10000'$ to test 10,000 values by default.
For an overview of the options available, see Gast's \verb$PrintOption$ and \verb$Testoption$ types.
\subsection{Compile test modules}
This step is optional and only included when \verb$--compile$ (\verb$-c$) is given.
This option is implied by \verb$--run$ (see below).
For compiling the test modules, \verb$clm$ is used, by default with the arguments \verb$-nt -nr$.
Add more arguments with \verb$--clm-arg$ (\verb$-C$).
Note that to give several arguments to \verb$clm$, this option must be repeated,
i.e. \verb$-C -h -C 100m$ and not \verb$ -C '-h 100m'$.
For convenience, \verb$testproperties$ accepts \verb$-I$ and \verb$-IL$ like \verb$clm$.
\subsection{Run test modules}
This step is optional and only included when \verb$--run$ (\verb$-r$) is given.
It implies \verb$--compile$ (see above).
When the step is included, every generated module is executed.
If a test fails, the return code of \verb$testproperties$ is non-zero, but the program will continue to test other modules (if any).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment