Home

Welcome to your wiki!

This is the default page, edit it as you see fit. To add a new page simply reference it within brackets, e.g.: [SamplePage].

The wiki uses Markdown syntax.

Project Members:

• Olivier Meurice (admin)

[Olivier Meurice]

Introduction

Picvert is an extensible automation tool written in Java initially developed to perform black box or end-user tests. It may also be used to automate other processes involving multiple systems.

To define a test scenario it is necessary to write a script using the simple Picvert script syntax.

The extensibility is obtained by adding new commands. It is achieved by
creating new classes that implement a specific interface. The new classes
must be packaged in a jar file that will be used by picvert at runtime.
Indeed the new command classes extend the command set that may be used in the Picvert script.

This documentation is updated during the development and therefore is in sync with the latest release.

When do you choose Picvert?

With Picvert you can automate any processing you want if you can code in Java.
Picvert comes with a set of commands but you can add your own.
You can run a UI test with Aigrette and check that some rows are inserted to the database for instance. Or you can call a REST service and check that an entry has been written to a log file.
And if a command is mising you can write it in Java and add it to the existing commands.

You can write your test plan, run it from your development station or from Jenkins (or any other CI tool compatible with JUnit report format) and check the test report from the Jenkins console.

[Olivier Meurice]

Installation

Install the binary package

Unzip the picvert-{version}.zip archive in the desired location.

Build from the sources

Prerequisites

Maven release > 3.0.5 must be installed and mvn command must be in the PATH.

Build Picvert

Get the sources from sourceforge.net
Open a shell and cd to the project root directory and run the command:
mvn clean compile package.
The archive picvert-{version}.zip is built in the picvert-core/target
directory.

[Olivier Meurice]

Running Picvert

Prerequisites

Install the JRE >= 1.7

Executing Picvert from the command line

Picvert is a Java program that is executed from the command line.
Here below the list of available parameters:

-l logfile
Specify the log file containing detailed information

-r reportfile
Specify the reporting file with valued information about test execution

-j xmlFile
Specify the Junit log file

-h
Print help about the available command

Example:

java -jar picvert-{version}.jar -l logger.log -r report.txt scenario.run
With scenario.run the picvert script file containing the commands to execute.

[Olivier Meurice]

Writing an automated scenario

So far the syntax of Picvert script is quite simple and was designed to
facilitate its parsing with few Java code.
A script is a text file with the "run" extension composed of a sequence of actions to perform each followed by its
comma-delimited parameters. The command and the parameters are separated by a
double colon (::).
Example:
COMMAND::PARAM1,PARAM2,...PARAMn

Internal commands

A collection of command are included in the tool and are obviously available
for scripting.
Run java picvert -h to get a list of available commands.

Variables

Picvert support a simple variable mechanism. Indeed some commands may store a
result in a variable that may be used later as another command parameter.

Example:
PUT::HELLO,VAR
ECHO::@VAR@

Executing this script will output "HELLO" to the console.

It also replace the variable by its value within a parameter value (placeholder):
ECHO::I said: @HELLO@

This will output: I said Hello

Loop

Two different loop are supported by Picvert.

The simple loop for executing a block of commands multiple times:

LOOP::2
ECHO::Looping
ENDLOOP

The concurrent loop to execute a block of commands multiple times in separated
threads:

CONCURRENT::2
ECHO::A thread has been created
ENDCONCURRENT

Conditional execution with if

To perform an action depending on the result of another action use the
IF/ENDIF commands:

PUT::1,VAR
IF::@VAR@,==,1
ECHO::VAR = 1
ENDIF

The IF command takes three parameters: a first value or variable, an operator and a
second value or variable. Invoke the help to get all the available
parameters.

Conditional loop with while

Sometimes it is useful to run an action while some condition is satisfied.
The WHILE command is very similar to the IF command:

PUT::NOK,VAR
WHILE::@VAR@,<>,OK
ECHO::Not OK!
PUT::OK,VAR
ENDWHILE

Comment

A comment may be inserted in the test script by adding a leading '#'.
For instance:

# This test just echoes a text
ECHO::A simple test

Advanced example

Example 1: we want to check a zip code from a database table

AIGRETTE!::uitest.xml
DBOPN!::org.postgresql.Driver,jdbc:postgresql://localhost:5432/jsrmicro,csr,password1,DBCON
DBSEL::@DBCON@,select zipcode from address where city = 'Brussels',RES
CHKRES::@RES@,1000

AIGRETTE runs a browser automation test that create a new adress entry in the application database
DBOPN opens a connection to the database and store the connection object in variable DBCON
DBSEL reuses DBCON to query the database and put the result in the array RES
CHKRES is a project specific command added in an external Picvert lib that checks that the value 1000 exist in the array RES. If the value is found a success code is returned and a success status is logged else a failure is returned and logged.
The exclamation mark (!) following commands AIGRETTE and DBOPN tells Picvert that the test execution must be stopped if one of these command fails.

In case of a command fails

If a command fails in a scenario then the scenario keep on with the execution of the following commands. But that is not always the expected behaviour.
To force the scenarion to stop its execution in case of a particular command fails then append the character '!' just next to the command name (thus between the command name and the '::' separator).

Test plan

With Picvert you can gather multiple test scenario into a single test plan. A test plan is a text file with the extension "pvt" containing a list of file path to scenario files.
A typical test plan file content look like this:

c:\project\test\scenario\testA.run
c:\project\test\scenario\testB.run

[Olivier Meurice]

Adding new command

Steps overview

Adding a new command is quite easy, just follow these steps:

Create a new class that implements IProcessor and extends
AbstractCommandProcessor from the picvert-api module.

Implement the method process(List<string> params, VariableStore store):
CommandResult where params is the parameters of the command and store contains all the variables with their values that have been initialized during the script execution. It is an IN/OUT parameter, that means that new data can be added to the store in the method implementation.
Also implement method validate(int parameterCount): CommandResult that will be called by the validator. This method should at least validate the command parameter count (see example below).
Then package the class in a new jar file and copy the Jar file in the extlib folder of picvert</string>

Add the package of the new command in the picvert.properties file
processor=com.mycompany.myfirstprj,com.mycompany.mysecondprj

Note that extlib folder and picvert.properties must be in the same directory
than the picvert jar file.

Accessing the parameter store

The second parameter of the IProcessor.process method is of type VariableStore and contains key/value pair for all variables it contains.
To get a variable value from the store call the getValue method with the variable name as parameter.
Adding a new variable is as simple as calling the addValue method with the variable name and its value as parameters.

Example

This is an example of a custom command that takes a string value from the variable store, append a timestamp and at the end put the result string value in the CommandResult instance. The name of the result string is also retrieved from the variable store.

package org.ome.example;
import org.ome.picvert.command.AbstractCommandProcessor;
import org.ome.picvert.command.Command;
import org.ome.picvert.command.CommandResult;
import org.ome.picvert.command.IProcessor;
import java.util.List;
import org.ome.picvert.command.scenario.VariableStore;

@Command(name = "EXAMPLE", description = "Append timestamp to string value", argumentDescriptions = {"value", "variable: variable name"})
public class ExampleCommand extends AbstractCommandProcessor implements IProcessor {
 @Override
 public CommandResult process(final List<string> params, final VariableStore store) {
  CommandResult result = new CommandResult();
  String value = params.get(0) + System.currentTimeMillis();
  result.addValue(params.get(1), value);
  result.addMessage("Value [" + value + "] put in variable [" + params.get(1) + "]");
  return result;
 }
 @Override
 public CommandResult validate(final int parameterCount) {
  CommandResult result = new CommandResult();
  if (parameterCount != 1) {
   result.setSuccess(false);
   result.addMessage(IProcessor.VALIDATION_WRONG_NUMBER_PARAM);
  }
  return result;
 }
}</string>

[Olivier Meurice]

Logging

Picvert is generating three outputs:

• A console log
• A technical text log which is appended at each run (same as console).
• A text report with very few details that summarize the tests executions, also appended.
• An XML Junit-formatted log that may be parsed by CI tools like Jenkins.

[Olivier Meurice]

Working with a database connection

Some commands for working with a database are included in the internal command set of Picvert:

• DBOPN to open a new connection
• DBSEL to run a query
• DBCLS to close an opened connection

Picvert is written in Java and therefore needs a JDBC driver to work with any database.
The JDBC library for the target database must be copied in the /extlib directory and the driver class must be specified in the DPOPN command.

For instance here is a command for opening a connection to a PostgreSQL database:

DBOPN!::org.postgresql.Driver,jdbc:postgresql://localhost:5432/databasename,user,password,DBCON

This command open a connection to the database 'databasename' of the local PostgreSQL with user 'user' and password 'password'. The connection object is put in the variable DBCON and will be available for subsequent operations (queries) with that database.

Let's see how we could perform a query:

DBSEL::@DBCON@,select zipcode from address where city = 'Brussels',RES

The command DBSEL is used to execute a query that get the zip code from the adress table for the city 'Brussels'. The result is an instance of List<object> put in the variable RES.

To get the zipcode of a city name that is given as parameter we could have written:

DBSEL::@DBCON@,select zipcode from address where city = @CITY@,RES

The variable CITY must obviously contain the name of the city we want to get the zipcode.

When we no longer need the database connection we can close it with the statement:

DBCLS::@DBCON@

</object>

[Olivier Meurice]

Release 1.2-SNAPSHOT

Picvert is now dependency version agnostic.
As a consequence upgrading Aigrette is as easy as renaming the latest aigrette-{release}.jar to aigrette.jar then copying the library to the Picvert lib folder.

Aigrette external libraries must be copied in the Picvert /extlib folder and aigrette.properties in the Picvert installation disrectory (where the jar files resides)
If required by the browser the path to the browser driver must be provided as JVM parameter. For instance testing with Chrome requires the use of a specific driver therefore its path must be provided:
-Dwebdriver.chrome.driver=chromedriver.exe

See Aigrette wiki for further information https://sourceforge.net/p/aigrette/wiki/Home/.