OERPScenario

by Camptocamp SA

V0.2 du 09.03.2010
 Open Source Base Camp

Table of content
1 Purpose of the document ........................................................................................... 3
1.1 Purpose......................................................................................................................... 3
1.2 Contact.......................................................................................................................... 3
1.3 Reviews......................................................................................................................... 3
2 Introduction.................................................................................................................. 4
2.1 What is OERPScenario ?...............................................................................................4
2.2 When to use OERPScenario?........................................................................................4
2.3 Why use OERPScenario?..............................................................................................5
2.4 The components of OERPScenario............................................................................... 6
2.5 How is it built ?...............................................................................................................6
3 Install and configure OERPScenario.......................................................................... 7
3.1 Install libraries and dependencies ................................................................................. 7
3.2 Get OERPScenario........................................................................................................ 7
3.3 How to configure it?....................................................................................................... 8
4 Running OERPScenario.............................................................................................. 9
4.1 Using simple tag............................................................................................................ 9
4.2 Advanced usage with tags and names...........................................................................9
4.3 Using the rake file........................................................................................................ 10
4.4 Output format............................................................................................................... 10
5 Writing a scenario : for business individuals..........................................................11
5.1 The Gherkin Syntax......................................................................................................11
5.2 Feature introduction..................................................................................................... 12
5.3 How to describe a test case?....................................................................................... 12
5.4 Where should I contribute to test writing?.................................................................... 12
6 Coding a Scenario : for technical individuals..........................................................13
6.1 Your first scenario........................................................................................................ 13
7 Technical docs........................................................................................................... 15
7.1 Using Helpers.............................................................................................................. 15
7.2 Using the Memorizer.................................................................................................... 16
7.3 Create an invoice and use workflow.............................................................................17
7.4 Use the Ruby console.................................................................................................. 17
7.5 Folder and files structures............................................................................................18
7.6 The Ooor and Cucumber doc.......................................................................................19
7.7 The Rdoc of OERPScenario........................................................................................ 19

v0.2 du 09.03.2010 Page : 2 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

1 Purpose of the document

1.1 Purpose
This document addresses the usage of OERPScenario, allowing to write business oriented
test cases in OpenERP. Parts of this text are excerpts from:
http://wiki.github.com/aslakhellesoy/cucumber/
This document is released under «Creative Commons»; the jurisdiction's law and
conditions are available here: http://creativecommons.org/licenses/by-sa/2.5/ch (or by mail
at Creative Commons, 171 Second Street, Suite 300, San Francisco, California 94105,
USA).

1.2 Contact
For any information, please contact:
Name Joël Grand-Guillaume

Title Camptocamp SA

Email openerp@camptocamp.com

Tel +41 21 619 10 10

Project OERPScenario

1.3 Reviews
Date Version Authors(s) Notes
07.10.09 0.1 JGE Initial version
03.09.10 0.2 SDE Editing

v0.2 du 09.03.2010 Page : 3 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

2 Introduction

2.1 What is OERPScenario ?

OERPScenario is a framework based on the Cucumber Library and the Ruby Language; it
uses the Ooor connector developed by Akretion to make Business Driven Development
(BDD) among OpenERP. It is a tool that can execute plain-text functional descriptions as
automated tests. Even though OERPScenario is written in Ruby, it only requires minimal
use of Ruby programming; Ruby is easy, so don’t be afraid if the code you are developing
is in another language .

OERPScenario allows business individuals to write a business scenario for a specific use
case and then allows technical individuals to parse the sentences to code the test case.
OERPScenario can address all OpenERP features and processes, use the demo data and
run the quality tests provided by the editor, OpenERP SA.

2.2 When to use OERPScenario?

This tool can be used in various contexts; it guarantees that the business processes are
well handled by OpenERP, producing the expected results.
It is primarily used for the following purposes:
• To ensure non-regressions through OpenERP versions;
• To provide a scenario to reproduce bugs and, as a consequence, ensure they are
fixed;
• To make Business Driven Development by first writing the business scenario then
coding the new features.

v0.2 du 09.03.2010 Page : 4 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

2.3 Why use OERPScenario?

OERPScenario is a powerful tool which provides solutions to easily write test cases for
OpenERP. Writing and handling test cases and business scenarios are usually complex
-but required- tasks in the world of ERPs.
Starting from here, OERPScenario splits tasks in two, allowing business individuals to write
and describe the different test scenarios, while technical individuals code the tests. This
really matters since technical individuals usually do not have a strong knowledge in the
business part (and reciprocally).
A summary of OERPScenario's advantages:
• Split the business and the technical part of test writing;
• Support all OpenERP features and processes (default values, on_change, wizards,
workflows,..);
• Modular, the tag system allowing you to run specific test cases according to your
OpenERP configuration;
• Based on Ruby ActiveResource, the well known Rspec / Cucumber tests and BDD
Library, it provides a very easy-to-use syntax to code tests;
• The scenario descriptions use the Gherkin Business Readable Domain Specific
Language, especially designed for use case description;
• Portions of a test can be re-used in another (so the more tests you code, the less
work is needed!);
• It is separated from OpenERP (in order to avoid ERP bugs' impact in the system). It
also allows to test several OpenERP servers from a single point.
• Even if it is not yet available, OERPScenario has everything to internationalize all
test cases.

v0.2 du 09.03.2010 Page : 5 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

2.4 The components of OERPScenario

2.5 How is it built ?

OERPScenario is mainly composed of three layers, providing a framework to make BDD
among OpenObject:

v0.2 du 09.03.2010 Page : 6 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

3 Install and configure OERPScenario

3.1 Install libraries and dependencies

You will need to install Ruby and the following packages to run OERPScenario:
• RubyGems
• Cucumber (V. 0.6.3)
• Rspec
• Parseconfig
• Ooor (V. 1.2.8+)
• Rake
• Htmlentities
• Optional for pdf output only
◦ Prawn (V.0.6.3)
◦ Pawn format (V. 0.2.3)
Here is an example on Ubuntu 9.10:
sudo apt-get install ruby irb ri rdoc rubygems
sudo gem install cucumber -v0.6.3
sudo gem install rspec
sudo gem install parseconfig
sudo gem install ooor --source http://gemcutter.org
sudo apt-get install libopenssl-ruby
sudo gem install rake
sudo gem install htmlentities
# Optional for pdf output only
sudo gem install prawn --version 0.6.3
sudo gem install prawn-format --version 0.2.3
# Finally add '/var/lib/gems/1.8/bin' to your PATH :
export PATH=$PATH:/var/lib/gems/1.8/bin

3.2 Get OERPScenario

You need to take the sources from Launchpad (make sure you have Bazaar installed on
your system).
To retrieve the stable branch (recommended):
bzr branch lp:oerpscenario

To retrieve the trunk branch:

bzr branch lp:oerpscenario/stable oerpscenario_stable

v0.2 du 09.03.2010 Page : 7 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

3.3 How to configure it?

You need to instruct OERPScenario on how to connect to the OpenERP server in a
configuration file. In order to do that, copy the file « sample_base.conf » as « base.conf »
into the OERPScenario folder and change the following information according to your
settings:
port = 8069
user = administrator
database = mydatabase
password = 12345
host = localhost

Once it's done, go into the OERPScenario folder and run the following command to test the
connexion:
rake compile

You should then have an output confirming everything is alright.

As the tests are running under a specific user, you can always change the one that has
been set-up as default (by default, all tests are running with the user defined in the config
file). If you need to run the tests under another user, edit the following file:
« /features/_basic/_init.feature » and change the sentence according to your needs:
Given I am logged as admin user with password admin used → Given I am logged as
administrator user with password 12345 used
The configuration is done!

v0.2 du 09.03.2010 Page : 8 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

4 Running OERPScenario

4.1 Using simple tag

The tag system implemented in Cucumber is very powerful and allows you to run complex
test cases according to your own OpenERP settings. Basically, the following tag types are
present in OERPScenario:
• Bazaar branch (like @addons), which tests all existing modules in that branch;
• Modules (likes @account), which tests everything having to do with a specific
module;
• Bugs related (like @bug452854), which launches the related scenario;
• Business oriented (like @invoicing), which runs every related scenario;
• System (like @init, @demo), which executes a set of tasks in OpenERP.

You can launch the test suite from the OERPScenario folder with the following commands:
cucumber feature --tag=@account

This will execute all scenarios related to the OpenERP account module (notice that tags
can be set on features or scenarios). The feature tags are true for all included scenarios,
where the scenario tags are true only for the current scenario.
Usually, running feature tags is enough, as they launch all included scenarios.

4.2 Advanced usage with tags and names

You can also execute tags-related scenarios with AND – OR – NOT operators. This allows
you to « build » the scenario you would like to check. This is especially useful since it
combines feature and scenario tags.
Using 'AND' between tags (run all scenarios matching all the given tags):
cucumber feature --tag=@init --tag=@account

Using 'OR' between tags (run all scenarios matching the given tags):
cucumber feature –tag=@init,@account

Using 'NOT' on a tag (run all scenarios except the given tags)
cucumber feature –tag=~@base

Find more information here: http://wiki.github.com/aslakhellesoy/cucumber/tags

Finally, you can launch the test suites according to a specific feature name:
cucumber feature –name « Initialize the settings »

Find more information, please go here :

http://wiki.github.com/aslakhellesoy/cucumber/running-features

v0.2 du 09.03.2010 Page : 9 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

4.3 Using the rake file

Rakefile is used to ease the launching of OERPScenario for standard tests. It launches the
test cases according to pre-selected settings which should fit in the most commonly used
use cases.
The supported command is the following:
• rake compile => Test that the package installation and configuration is well
done
• rake demo => Install the demo data on installed modules (running the assert
tests)
• rake quality => Launch the base quality module provided by OpenERP SA
• rake account => Initialize the OpenERP instance and launch the accounting
test suites
• rake sale => Initialize the OpenERP instance and launch the sales test
suites
In a near future, we'll add other useful commands. Since you don't have to know each tags,
this is going to be the way non-technical individuals launch the OERPScenario test suite.

4.4 Output format

You can change the default console output format to get your results in an other one. There
are quite a lot of different formats available. Please refer to the help section:
cucumber --help

Here, is a way to have it in a nice looking html:

cucumber features --tag=@sample --format=html --out=/tmp/result.html

..or in .pdf (if you install the required package):

cucumber features --tag=@sample --format=pdf --out=/tmp/result.pdf

The format option also allows you to print out various information while running tests, like
the line number of the step_definition for example.

v0.2 du 09.03.2010 Page : 10 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

5 Writing a scenario : for business individuals

5.1 The Gherkin Syntax

Gherkin is the language that Cucumber and OERPScenario understand. It is a Business
Readable, Domain Specific Language that lets you describe software’s behavior without
detailing how that behavior is implemented.
Gherkin primarily serves two purposes: documentation and automated tests. The third
purpose is a bonus feature , guiding you what code you should write.
Gherkin’s grammar is defined in the Treetop grammar, being part of the Cucumber
codebase. The grammar exists in different types and in many languages (37 at the time of
writing), so that your team can use the keywords in your own language.
There are a few conventions to go by:
• Single Gherkin source file contains a description of a single feature
• Source files have .feature extension
Gherkin is a line-oriented language that uses indentation to define structure. Line endings
terminate statements (eg, steps). Either spaces or tabs may be used for indentation (but
spaces are more portable). Most lines start with a keyword.
Comment lines are allowed anywhere in the file. They begin with zero or more spaces,
followed by a sharp sign (#) and some amount of text.
Parser divides the input into features, scenarios and steps. When you run the feature, the
trailing portion (after the keyword) of each step is matched to a Ruby code block called step
definition.
A Gherkin source file usually looks like this:
1: Feature: Some terse yet descriptive text of what is desired
2: In order to realize a named business value
3: As an explicit system actor
4: I want to gain some beneficial outcome which furthers the goal
5:
6: Scenario: Some determinable business situation
7: Given some precondition
8: And some other precondition
9: When some action by the actor
10: And some other action
11: And yet another action
12: Then some testable outcome is achieved
13: And something else we can check happens too
14:
15: Scenario: A different situation
16: ...

First line starts the feature. Lines 2-4 are unparsed text, which is expected to describe the
business value of this feature. Line 6 starts a scenario. Lines 7-13 are the steps for the
scenario. Line 15 starts next scenario and so on.

v0.2 du 09.03.2010 Page : 11 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

5.2 Feature introduction

Every feature file conventionally consists of single feature. Line starting with keyword
Feature followed by free indented text starts a feature. Feature usually contains a list of
scenarios. You can write whatever you want up until the first scenario, which starts with the
word « Scenario » (or localized equivalent, Gherkin is localized for dozens of languages) on
a new line. You can use tagging to group features and scenarios together independent of
your file and directory structure.
Every scenario consists of a list of steps, which must start with one of the keywords -Given
– When – Then – But - or - And-. Cucumber treats them all the same, but you shouldn’t.
Here is an example:
Feature: Serve coffee
In order to earn money
Customers should be able to
buy coffee at all times

Scenario: Buy last coffee

Given there are 1 coffees left in the machine
And I have deposited 1$
When I press the coffee button
Then I should be served a coffee

For each step, Cucumber will look for a matching step definition. A step definition is written
in Ruby and can parse part of the step words with regular expressions to perform the test.

5.3 How to describe a test case?

It's never easy to describe a Business scenario. In order to ease this task, there are some
tips. First, have a look on already implemented tests. Run OERPScenario and re-use all
possible sentences. Since OERPScenario can use a sentence as many times as needed
and in different scenarios, don't hesitate to copy / paste portion of existing tests.
Then, ensure you define all needed « pre » conditions to run the test. It's very important
that you don't miss some information (for example, the specific Account Journal settings or
the type of delivery you selected before confirming the sale order). If you don't feel
comfortable with initialization settings in the « _pre.feaure » files, it is important that you
explain why directly in the test case.
Individuals coding your test will then understand the requirement to run it properly. On this
base, they'll be able to include the initialization settings in the right place.

5.4 Where should I contribute to test writing?

We decided to use the OERPScenario's blueprint on Launchpad to manage the different
test case definitions. If you want to contribute to define them, feel free to write your new
blueprints here: https://blueprints.launchpad.net/oerpscenario
We'll provide you feedback on your description and will let you know the required
modifications we operated in order to implement the test.

v0.2 du 09.03.2010 Page : 12 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

6 Coding a Scenario : for technical individuals

6.1 Your first scenario

In order to let you understand a basic scenario, we are going to give you a simple example.
First of all, create a folder into /features called « my_scenario ». In it, create a text file
called « sample.feature » and a folder called « step_definitions ».
Then, you need to write the business case using the Gherkin Syntax into the
« sample.feature » :
1. # Features Generic tags (none for all)
2. ##############################################################################
3. # System
4. @sample_test
5. Feature Make some scenario samples
6. In order to show you how to work with OERPScenario

7. I want to illustrate the basics behaviors

8. Scenario: Sample Create a partner and test some basic stuffs
9. Given I want to show you how to use OERPScenario
10. When I create a partner named automatedtest
11. Then I should be able to find it by his id
12. And the name should be automatedtest

Notice the following things:

• Line 4. Adds the tag for the current feature (used in every contained scenario);
• Line 5. The keyword « Feature » starts the test case (composed by scenario);
• Line 6. & 7. Between « Feature » and the « Scenario » keyword, write anything you
want;
• Line 8. The keyword « Scenario » starts the first scenario of the feature;
• Line 9-12 Scenario description using the Gherkin Syntax.

Once you save the file, run OERPScenario with the following command:
cucumber features --tag=@sample_test

This will run the background first (as it is for every scenario), then your new test.

v0.2 du 09.03.2010 Page : 13 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

No steps exists for the specified sentence, so OERPScenario ask you to define it, informing
how it should parse and execute the action you described.
You can implement step definitions for undefined steps with these snippets:
Given /^I want to show you how to use OERPScenario$/ do
pending # express the regexp above with the code you wish you had
end
When /^I create a partner named automatedtest$/ do
pending # express the regexp above with the code you wish you had
end
Then /^I should be able to find it by his id$/ do
pending # express the regexp above with the code you wish you had
end
Then /^the name should be automatedtest$/ do
pending # express the regexp above with the code you wish you had
end

Copy these lines and paste them in a new created text file called « sample_step.rb » into
the « step_definitions » folder.
For the first sentence, we expect nothing special to be done, so just remove the pending
keyword and let this step empty.
For the second sentence, we want to create a partner called automatedtest; change it with :
When /^I create a partner named (\w+)$/ do |name|

This will take all the text after « named » and put it into the name variable. Then write that
into the step:
1. # Create a new partner using Ooor, and store it in a
2. # global var for the current feature
3. @partner = ResPartner.new(:name => name)
4. @partner.create
5. # Controle it has been a success
6. @partner.should be_true

For the third step, implement the following:

1. # Find the partner by id
2. result=ResPartner.find(@partner.id)
3. # Test we get something
4. result.should be_true
5. # Store it into @partner to have it for the next step
6. @partner=result

Finally, the last one should look like:

Then /^the name should be (\w+)$/ do |name|
# Test the name is correct
@partner.name.should == name
end

You can now run OERPScenario with the tag @sample_test, and every step should pass.
Find the complete example in the « samples » folder.

v0.2 du 09.03.2010 Page : 14 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

7 Technical docs
The best technical documentation will probably be the already coded test cases. Because
all operations are explicitly written in the test case description, you will easily understand
what the code found in the step represents. Below you will find some advices to help you
get the basic concept.

7.1 Using Helpers

Helpers are here to ease the step writing with specific functions added to an OpenObject
model. As it's hard to setup the right state to properly code a business case, we added
some useful features, such as creating a valid invoice with just one line.
Feel free to extend those Helpers based on your needs. Here are a few examples taken
from the « samples » folder:
# ##############################################################################
Given /^I want to show you how to use the Helpers$/ do
end
# ##############################################################################
When /^you need to look for a supplier partner with at least one contact$/ do
end
# ##############################################################################
Then /^you can use one of the ResPartner helper called get_valid_partner$/ do
# Use the ResPartner Helper to get a partner of a certain type
# and with at least one address
@partner=ResPartner.get_valid_partner({:type=>'supplier'})
@partner.should be_true
end
# ##############################################################################
Then /^get the corresponding partner very easily$/ do
# Check it's a supplier
@partner.supplier.should be_true
# Check it has a contact
@partner.address.count.should > 0
end

Find all available Helpers in the /lib/Helpers folder of OERPScenario.

v0.2 du 09.03.2010 Page : 15 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

7.2 Using the Memorizer

As variable scope does not cross the scenarios, we designed a little Memorizer to allow
you to use an object through various scenarios.
This Memorizer takes 2 arguments: the object to store and the variable name to use.
Please find an example below from the « sample » folder of OERPScenario:
# ##############################################################################
Given /^I store it into the memorizer as (\w+) in order to retrieve it in another
scenario$/ do |var_name|
# Memorize the partner in order
# to retrieve it again when needed in another
# scenario or feature
$utils.set_var(var_name,@partner)
end
# ##############################################################################
Given /^I call back the memorizer to retieve the (\w+) variable$/ do |var_name|
@Memorized_partner=$utils.get_var(var_name.strip).should be_true
end
# ##############################################################################
Then /^I should have the same partner as contained into @partner variable$/ do
@Memorized_partner.id.should == @partner.id
end

v0.2 du 09.03.2010 Page : 16 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

7.3 Create an invoice and use workflow

You can call for workflow actions based on their names, such as in the following example,
where we create an invoice and open it. You can find the full example into the « samples »
folder.
Given /^I have recorded a supplier invoice of (.*) (\w+) called (\w+) using Helpers$/ do
|amount, currency, name|
# Take first supplier partner with at least one address
@partner=ResPartner.get_valid_partner({:type=>'supplier'})
@partner.should be_true
# Create an invoice with a line = amount
@invoice=AccountInvoice.create_invoice_with_currency(name, @partner,
{:currency_code=>currency, :amount=>amount.to_f, :type=>'in_invoice'})
@invoice.should be_true
end
# ##############################################################################
When /^I validate the invoice using the validate button$/ do
# Call the 'invoice_open' method from account.invoice openobject
@invoice.wkf_action('invoice_open')
end
# ##############################################################################
Then /^I should get the invoice (\w+)$/ do |state|
# Take the invoice and check the state
@invoice.should be_true
@invoice.state.should == state
end

7.4 Use the Ruby console

Through the « irb » command, you can call Ooor and establish a connexion to an
OpenERP server. From here, you can either tests the syntax or get information about the
object structures. This is very useful to understand how to code something. First of all,
launch the Ruby console and connect Ooor to your OpenERP server:
irb
require 'rubygems'
require 'ooor'
Ooor.new({:url => "http://localhost:8069/xmlrpc", :database => "cucumber", :username =>
"admin", :password => "admin"})

From here, you can type any command you want. Try this one to get a nonexistent field
from ResPartner model. Ooor will even return you what is accessible:
a=ResPartner.find(:first)
a.x

Test everything you need through this console. It is recommended to take a look at the
Ooor documentation to know more about ActiveRessource on OpenObject:
http://github.com/rvalyi/ooor

v0.2 du 09.03.2010 Page : 17 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

7.5 Folder and files structures

v0.2 du 09.03.2010 Page : 18 / 19

Formation_OERPScenario_v0.2.odt
 Open Source Base Camp

7.6 The Ooor and Cucumber doc

We strongly invite you to visit these pages as you will find a lot of hand-on examples:
http://github.com/rvalyi/ooor
http://wiki.github.com/aslakhellesoy/cucumber/

7.7 The Rdoc of OERPScenario

You can find the auto-generated rdoc into the « doc » folder. To update it, just run the
following command from OERPScenario folder:
rdoc

You can access it by opening the index.html

v0.2 du 09.03.2010 Page : 19 / 19

Formation_OERPScenario_v0.2.odt