manual.tex

\documentclass{article}
\usepackage{listings}
\usepackage{textcomp}

\lstdefinestyle{luastyle}
{
  language         = {[5.2]Lua},
  basicstyle       = \ttfamily,
  showstringspaces = false,
  upquote          = true,
}
\lstset{style=luastyle}

\title{Automated Test Framework \\ \vspace{2mm} \large User Manual}
\author{Dmitry Chmerev}

\begin{document}

\begin{titlepage}
\maketitle
\end{titlepage}

\tableofcontents
\clearpage

\section{ATF basics}
ATF is a set of Lua classes and extensions providing a simple way to create,
manage and use network connections, process Applink protocol messages
and use HMI protocol --- everything needed for communication with SDL.
It's generally a library for black-box test development for SDL.

Test consists of several use cases --- a set of data to be sent to input
SDL channels and data expected to be received from SDL output.

\section{Test script structure}
Because ATF test runner is merely a Lua interpreter, test script is just
a Lua program.
The script should create a Test table, using one of base scripts,
add some test cases and return this table to allow another test script
to extend this test with new cases.
Test cases should be implemented as functions with only argument --- Test
table.
Test case function name must start with a capital letter.
Basically a test case fills expectations table (see~\ref{expectations table})
and sends a fixed message to SDL.
When SDL responds, expectations are verified, and if all expectations have
been satisfied, the test case is considered passed.

The base test creates two connection to SDL --- mobile connection and HMI
connection, and initializes them.
Then an application is registered using {\tt RegisterAppInterface} call.

\section{Test cases}
Test cases are functions, belonging to the Test table. Their name must begin
with a capital letter. To describe the purpose of the test case, use
{\tt desciption(str)} function. It takes one string argument -- description.
To make a test case critical -- that is, if this case fails, the Test will
not continue execution, call {\tt critical(true)}.

\section{Expectations creating}
To specify what data is expected to be received from SDL, the Expectations
Table\label{expectations table} is used.
Every item of this table describes single message.
To simplify Expectations writing ATF provides several functions making typical
expectations.
\subsection{\tt EXPECT\_RESPONSE(correlationId, arguments, ...)}
Returns expectation of mobile connection input.
This function takes following arguments: the first, {\tt correlationId}, is the
correlation identifier of response expected.
The latter ones, {\tt arguments}, are optional tables of expected response
arguments.
If expectation has complied more than once, arguments are checked against last
arguments parameter.
\subsection{\tt EXPECT\_NOTIFICATION(funcName, arguments, ...)}
Returns expectation of mobile connection notification.
The function takes two arguments: {\tt funcName}, name of notification,
and optional {\tt arguments}, which are used to verify notification data.
\subsection{\tt EXPECT\_ANY}
Returns expectation of any unexpected activity on mobile session.
\subsection{\tt EXPECT\_ANY\_SESSION\_NOTIFICATION(funcName, arguments, ...)}
Returns expectation of notification to any session.
\subsection{\tt EXPECT\_EVENT(event, name)}
Returns expectation of custom event
\subsection{\tt EXPECT\_HMIRESPONSE}
Returns expectation of {\sc hmi} connection data.
The only argument, {\tt id}, is identifier of request sent.
\subsection{\tt EXPECT\_HMINOTIFICATION}
Returns expectation of an {\sc hmi} notification from {\sc sdl}.
\section{Expectations extensions}
Expectations may be extended with some extra specifications.
They are intended to be used in call chain: programmer can improve expectation
parameters by calling following methods one after one.

\noindent Example:
\begin{lstlisting}
EXPECT_NOTIFICATION("OnHMIStatus")
  :Timeout(5000)
  :Times(AnyNumber())
  :Do(function() print("OnHMIStatus got") end)
\end{lstlisting}
\subsection{Times}
If you want an expectation to occur several times, add {\tt Times} call
to expectation.

\noindent Example:
\begin{lstlisting}
EXPECT_NOTIFICATION("OnHMIStatus")
  :Times(2)
\end{lstlisting}
{\tt Times()} arguments may be one of following values:
\begin{itemize}
\item $x$ or Exactly($x$), to specify that expectation should occur exactly $x$
times to get passed.
Particularly, {\tt Times(0)} means that expectation will fail test if occur
\item AtMost($x$) --- expectation should occur $x$ or fewer times
\item AtLeast($x$) --- expectation should occur $x$ or more times
\item Between($x$, $y$) --- expectation should occur between $x$ and $y$ times
\item AnyNumber() --- expectation may occur or not
\end{itemize}
\subsection{\tt Do, DoOnce}
These two functions takes one argument --- function that will be called when
expectation complied.
This callback function will be called with two arguments: complied expectation
and incoming data.
{\tt Do} function registers callback forever, {\tt DoOnce} --- for the first
trigger only.
\subsection{\tt Timeout}
Default expectation timeout is 10 000 ms.
To change it, call {\tt Timeout} function with new timeout value in milliseconds.
\subsection{\tt Pin, Unpin}
Pinned expectation is not to be removed when test case is finished.
This ability is used generally for some service expectations (timeout controllers,
notification handlers etc.)
To make the expectation pinned, call {\tt Pin()} extension.
To unpin it, call {\tt Unpin()}.
\subsection{\tt ValidIf}
In some cases the standard {\sc rpc} validation routine is not enough to verify
expectation data.
Use {\tt ValidIf} function to register verifying callback that would be used
when expectation complied.
Callback should take two arguments: expectation object and data table.
If data is valid, function must return {\tt true}, otherwise it must return
two values: {\tt false} and error message to be displayed in test report.
\section{Requests sending}
The connectivity test provides two connections to {\sc sdl} channels:
{\tt mobileSession} and {\tt hmiConnection}.

\subsection{Mobile side}
To send a request from mobile application side, call
{\tt mobileSession:SendRPC(message, filename)}.
This function returns {\tt correlationId} field of request has been sent.
{\tt filename} is optional.
If is not {\tt nil}, the file contents added to {\sc rpc} request binary data.
For example,
\begin{lstlisting}
self.mobileSession:SendRPC("Alert", { alertText1 = "Hello" })
self.mobileSession:SendRPC("PutFile",
                           {
                             syncFileName = "icon.png",
                             fileType = "GRAPHIC_PNG"
                           },
                           "icon.png")
\end{lstlisting}

To send an arbitrary message, use {\tt Send} method.
It takes the Applink message, the following fields are supported:
\begin{itemize}
\item version (optional, default 2) Version of message
\item encryption (optional, default false) Encryption flag
\item frameType (optional, default 1) Frame Type field
\item serviceType (required) Sevice Type field
\item frameInfo (required) Frame Info field
\item rpcType (required) If serviceType is 7, type of {\sc rpc} request
\item rpcFunctionId (required) {\sc rpc} function id
\item rpcCorrelationId (required) {\sc rpc} correlation id
\item payload (required) {\sc json} payload of {\sc rpc} request
\item binaryData (optional) binary data of message or {\sc rpc} request
\end{itemize}

\subsection{{\sc hmi} side}
{\tt HMIConnection} provides functions similar to {\tt MobileSession}'s.
\begin{itemize}
  \item {\tt SendRequest(method, params)} Sends {\sc hmi} request, returns id of sent message.
  \item {\tt SendNotification(method, params)} Sends notification with parameters.
  \item {\tt SendResponse(id, method, result, params)} Sends response to request with specified
  id, method name. {\tt result} field is a name of result code.
  For example, {\tt "SUCCESS"} or {\tt "ABORTED"}.
  \item {\tt Send(text)} Sends arbitrary text through {\sc hmi} connection.
\end{itemize}
To send a message from {\sc hmi} side, use {\tt hmiConnection:Send(message)}.
We will add some more convenient methods later.
For example,
\begin{lstlisting}
self.hmiConnection:Send({
                          jsonrpc = "2.0",
                          method = "UI.OnSystemContext",
                          params =
                          {
                            appID = 100,
                            systemContext = "ALERT"
                          }
                        })
\end{lstlisting}

\section{Services}
To start a service use {\tt MobileSession:StartService(n)} function.
It takes service number and returns expectation awating for
{\tt StartServiceACK} message.
To end service, call {\tt MobileSession:StopService(n)}.

Example:
\begin{lstlisting}
self.mobileSession:StartService(11)
  :Do(function() print("Service started") end)
\end{lstlisting}

\section{Media streaming}
{\sc atf} allows to start media streaming in background.
Use {\tt MobileSession:StartStreaming(service, filename, bandwidth)} to start media streaming.
Optional {\tt bandwidth} argument sets maximum bandwidth of streaming (bytes per second).
Default is 30~kbps.
Note that the service should be started before {\tt StartStreaming} is called.

Example:
\begin{lstlisting}
self.mobileSession:StartService(10)
  :Do(function() self.mobileSession:StartStreaming(10, "video.mpg", 30 * 1024) end)
\end{lstlisting}
To stop file streaming, call {\tt StopStreaming(filename)}.
\section{Auxiliary functions}
\subsection{\tt RAISE\_EVENT(event, data)}
Raises custom event with optional data. If there is an expectation it will be satisfied.
\subsection{RUN\_AFTER}
Use {\tt RUN\_AFTER} routine to postpone function execution.\\
Usage: {\tt RUN\_AFTER(function, timeout)}.
The function will be called in {\tt timeout} msec.
\end{document}