Verified Commit c3c0d4a1 authored by Camil Staps's avatar Camil Staps 🚀

Update documentation

parent 73dc9e7c
Pipeline #18579 passed with stage
in 1 minute and 16 seconds
\section{Examples}
Examples using clean-test-properties can currently be found in experimental branches in Platform:
The author knows about the projects using clean-test-properties listed below.
To find the right modules, the easiest is to clone the repository and grep for \texttt{@property}.
\begin{itemize}
\item \url{https://gitlab.science.ru.nl/clean-and-itasks/clean-platform/merge_requests/131};
\item \sloppy\url{https://gitlab.science.ru.nl/clean-and-itasks/clean-platform/compare/master...geometryProperties}.
\item \url{https://gitlab.science.ru.nl/clean-and-itasks/clean-platform};
\item \url{https://gitlab.science.ru.nl/cloogle/cloogle-org}.
\end{itemize}
\section{Installation}
Clean-test-properties is not yet included in any distribution, so you have to build the tool yourself.
Clean-test-properties is included in the nightly builds which can be downloaded from \url{https://ftp.cs.ru.nl/Clean/builds/}.
Alternatively, you can build the tool from source.
On Linux and Mac, you can clone the repository and run \bash{make} to fetch dependencies and build the binary:
\begin{Verbatim}
git clone https://gitlab.science.ru.nl/clean-and-itasks/clean-test-properties
cd clean-test-properties
cd clean-test-properties/src
make
\end{Verbatim}
......@@ -116,14 +116,17 @@ This serves two main functions:
\subsubsection{\clean{@property-test-generator}}
\label{sec:property-test-generator}
\availableon{modules}
In some cases, Gast's value generation is not suitable for generating useful test cases.
In particular this is the case for types as \clean{Map} and \clean{Set} which assume that some properties hold for their values
For some types, Gast's generic value generation does not generate very useful test cases.
For these types one can specify different test generators in several ways.
\paragraph{Value transformers}
Some types, such as \clean{Map} and \clean{Set}, assume that some properties hold for their values
(while these properties cannot be ensured by the type system).
When testing such types, it is custom to use a \enquote{shadow type} to generate values and transform the shadow type to the tested type.%
\footnote{Common shadow types are \clean{[(k,v)]} for \clean{Map k v} and \clean{[a]} for \clean{Set a}.}
Inconveniently, classic testing with Gast then requires one to specify properties on the shadow type instead of the actual type and call the value transformer from every test.
Clean-test-properties can automate this process by defining a file-global test generator containing the value transformer.
One can automate this process by defining a file-global test generator containing the value transformer.
A typical test generator for \clean{Set} would look like:
\begin{Verbatim}
......@@ -140,6 +143,18 @@ When multiple test generators are applicable, one is picked arbitrarily.
For a generator to be recognised by clean-test-properties it must have the \emph{exact same} result type as the argument used in the property.
This means that a property with arguments of type \clean{Set b} will \emph{not} use the test generator specified above, because the type variables do not match.
\paragraph{Predefined lists}
A different type of test generator takes values from a list.
Internally, it uses Gast's \clean{ForEach} property combinator.
The test generator header should start with \texttt{list:} and then list the type for which values are generated.
The rest of the test generator contains the implementation of the list.
For example:
\begin{Verbatim}
* @property-test-generator list: Int
* [0..10]
\end{Verbatim}
\subsubsection{\clean{@property-test-with}}
\label{sec:property-test-with}
\availableon{modules; functions}
......
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