Suivre les stats de son site web en Ruby On Rails avec Piwik

april, debian-fr, planet-cullt, planet-libre

Suivez-moi aussi sur Identi.ca  ou Twitter  ou Diaspora*diaspora-banner

Après avoir lancé Le Journal du Pirate, le Hacker News francophone, j’avais évidemment besoin de suivre la fréquentation du site. J’avais utilisé AWStats sur un précédent projet et je voulais tenter d’utiliser un logiciel de comception un peu plus récente cette fois-ci.

awstats-logo

Piwik semblait convenir parfaitement. Multi-sites, Interface graphique moderne, des bons échos dans la communauté, je me suis donc naturellement dirigé vers cette solution. Piwik se présente comme une application web avec une base de données MySQL derrière.

piwik_app

Pour les gens intéressés, le site officiel propose une démo très sympa permettant de voir tout de suite les points forts de Piwik.

piwik

Le Journal du Pirate est quant à lui une application Ruby On Rails. Or Piwik requiert l’ajout d’un javascript sur les pages que l’on veut surveiller. Ce qui peut s’avérer délicat à réaliser lorsque que l’on maîtrise mal RoR.

La documentation officielle suivante explique très bien la marche à suivre. Ajouter une gem Ruby à son Gemfile, relancer bundle puis quelques éléments de configuration dans le fichier config/piwik.yml et le tout a marché directement.

rails

Je suis très content du résultat. Niveau interface graphique c’est très agréable et Piwik propose un très grand nombre de métriques associées aux différents sites web supervisés. J’en ai profité pour lui faire surveiller ce blog et le site web de MyTux, ma société d’infogérance de serveurs Debian.

Et vous ? Quel est votre ressenti après avoir utilisé quelques temps Piwik ? Des difficultés à le mettre en place avec RoR ? N’hésitez pas à réagir dans les commentaires de ce billet.

Site comme Hacker News en français : Le Journal Du Pirate

april, debian-fr, planet-cullt, planet-libre, python

Suivez-moi aussi sur Identi.ca  ou Twitter  ou Diaspora*diaspora-banner

Avant tout l’adresse du site : Le Journal Du Pirate https://infos.mytux.fr

Un site web comme Hacker News mais francophone propulsé par un Logiciel Libre, je trouve que ça manquait à la communauté francophone.

ycombinator-logo

C’est maintenant chose faite avec un site dérivé du moteur de Lobste.rs. Les sources sont disponibles sur ce GitHub.

github-logo

L’inscription fonctionne par cooptation pour limiter les articles indésirables.

Un petit commentaire avec votre e-mail dans le champ des e-mails et je vous fais parvenir une invitation, qui vous permet à votre tour d’inviter autant de personnes que vous le souhaitez.

Vous pouvez aussi réclamer une invitation depuis le site. L’un des utilisateurs courants vous enverra alors une invitation.

Et tous les commentaires sont les bienvenues bien sûr ;)

Send the same short message on Twitter, Pump.io, Diaspora*… and a lot more

debian, planet-cullt, sysadmin

Follow me on Identi.ca  or Twitter  or Diaspora*diaspora-banner

This is a feedback about installing a self hosted instance of Friendica on a Debian server (Jessie). If you’re not interested in why I use Friendica, just go to « Prerequisite for Friendica » section below.

Frustration about social networks

Being a huge user of short messages, I was quite frustated to spend so much time on my Twitter account. To be quite honest, there is no much I like about this social network, except the huge population of people being potentially interested in what I write.

twitter-logo

I also have been using Identi.ca (now powered by Pump.io) for a while. But I tried for a while to manage both networks Pump.io and Twitter by hand and it was quite painful. And something was telling me another social network was going to appear from nowhere one of these days and I’ll be just horrible to try to keep it up this way.

identica-logo

So I was looking for a « scalable » solution not asking too much personal investment. Subscribing to Diaspora* some days ago on the Framasphere pod, tintouli told me to try Friendica.

Hmmm, what’s Friendica ?

f-intro

Friendica is a content manager you can plug on almost anything: social networks (Facebook, Twitter, Pump.io, Diaspora*,…), but also WordPress, XMPP, emails… I’m in fact just discovering the power of this tool but to plug it on my different social network accounts was quite a good use case for me. And I guess if you’re still reading, for you too.

I tried to use some shared public servers but I was not quite happy with the result, one connector was still missing or public servers were really unstable. So I’m at last self hosting my Friendica. Here is how.

Prerequisite for Friendica

You need to install the following packages:

# apt-get install apache2 libapache2-mod-php5 php5 php5-curl php5-gd php5-mysql mysql-server git

Having a already self-modified /etc/php5/apache2/php.ini, I encountered a small issue with libCurl and had to manually add the following line in the php.ini:

extension=curl.so

Setting up MySQL

Connect to MySQL and create an empty database with a dedicated user:

# mysql -u root -pV3rYS3cr3t -e « create database friendica; GRANT ALL PRIVILEGES ON friendica.* TO friendica@localhost IDENTIFIED BY ‘R3AlLyH4rdT0Gu3ss' »

mysql

Setting up Apache

My server hosts several services, so I use a subdomain friendica.mydomain.com. If you use a subdomain, of course check you do have declared this subdomain in your DNS zone.

apache-logo

I use SSL encryption with a wildcard certificate for all my subdomains. My Friendica data are stored in /var/www/friendica. Here is my virtual host configuration for Friendica stored in the file /etc/apache2/sites-available/friendicassl.conf :

<VirtualHost *:443>
ServerName friendica.mydomain.com
DocumentRoot /var/www/friendica/
DirectoryIndex index.php index.html
ErrorLog /var/log/apache2/friendica-error-ssl.log
TransferLog /var/log/apache2/friendica-access-ssl.log

SSLEngine on
SSLCertificateFile /etc/ssl/certs/mydomain/mydomain.com.crt
SSLCertificateKeyFile /etc/ssl/private/mydomain.com.key
SSLVerifyClient None

<Directory /var/www/friendica/>
AllowOverride All
Options FollowSymLinks
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

After writing the configuration file, just launch the following commands and it should be good for the Apache configuration:

# a2ensite friendicassl && /etc/init.d/apache2 reload

friendica-trust

Setting up Friendica

Get the master zip file of Friendica, copy it on your server and decompress it. Something like :

# cd /var/www/ && wget https://github.com/friendica/friendica/archive/master.zip && unzip master.zip && mv friendica-master friendica

You need to give www-data (Apache user) the rights to write in /var/www/friendica/view/smarty3/ :

# chown -R www-data:www-data /var/www/friendica/view/smarty3 && chmod -R ug+w var/www/friendica/view/smarty3

Ok, I guess we’re all set, lets launch the installation process! Using your web browser, connect to friendica.mydomain.com. First step you’ll see the installation window which checks the prerequisite before installing. Complete if something is missing.

friendica-installation

First window of the Friendica installation process

Second step asks the host/user/password of the database, complete and the installation process starts. Hopefully all goes just fine.

Next you’ll have to create a /var/www/friendica/.htconfig.php with the content that the last page of the installation process provides. Just copy/paste, check the rights of this file and now you can connect again to see the register page of friendica at the url https://friendlica.mydomain.com/register . Pretty cool!

Register a user

That’s a fairly easy step. You just need to check before that your server is able to send emails, because the password is going to be sent to you by email. If it is ok, you should now identify on the welcome page of friendica and access your account. That’s a huge step to broadcast your short messages everywhere, but we have some last steps before being able to send your short messages on all the social networks we need.

A small break, create an app for twitter on apps.twitter.com

To send your short messages to Twitter, you need to create an app on apps.twitter.com. Just check you’re logged in Twitter and connect to apps.twitter.com. Create an app called with a unique name (apparently), then go to the Keys and Access tokens page, note the consumer key and the consumer secret. You’ll later need the name of the app, the consumer key and the consumer secret.

friendica-decentralized-network

Install and configure the addons

Friendica uses an addon system in order to plug on the different third-parties it needs. We are going to configure Twitter, Pump.io and the Diaspora* plug. Let’s go back to our server and launches some commands:

# cd /tmp && git clone https://github.com/friendica/friendica-addons.git && cd friendica-addons

# tar xvf twitter.tgz -C /var/www/friendica/addon

# tar xvf pumpio.tgz -C /var/www/friendica/addon

# cp -a diaspora /var/www/friendica/addon

You need to modify your /var/www/friendica/.htconfig.php file and add the following content at the end:

// names of your addons, separated by a comma

$a->config[‘system’][‘addon’] = ‘pumpio, twitter, diaspora';

// your Twitter consumer key
$a->config[‘twitter’][‘consumerkey’] = ‘P4Jl2Pe4j7Lj91eIn0AR8vIl2′;

// your Twitter consumer secret
$a->config[‘twitter’][‘consumersecret’] = ‘1DnVkllPik9Ua8jW4fncxwtXZJbs9iFfI5epFzmeI8VxM9pqP1′;

// you Twitter app name

$a->config[‘twitter’][‘application_name’] = « whatever-twitter »;

banner_friendica

Connect again to Friendica. Go to settings => social networks, you will see the options for Twitter, Pump.io and Diaspora*. Complete the requested information for each of them. Important options you should not forget to check are:

Pump.io

  • Enable pump.io Post Plugin
  • Post to pump.io by default
  • Should posts be public?

Twitter

  • Authorize publication on Twitter
  • Post to Twitter by default

Diaspora*

  • Post to Diaspora by default

Done? Now it’s time to send your first broadcasted short message. Yay!

Send a short message to your different social networks

Connect to Friendica, click on the network page, write your short message in the « Share » box. Click on the lock lock, you’ll see the following setup:

friendica-post-default

It means your short messages will be broadcasted to the three networks. Or more, it’s up to you! That’s my setup, feel free to modify. Now close the lock window and send your message. For me it takes some time to appear on Twitter and Diaspora* and it immediatly appears on Identi.ca.

Last words

friendica-stand

Friendica offers to take back the control of your data, by broadcasting content on different media from a single source. While self hosting, you keep your data whatever happends and are not subject to companies losing your data like recently Twitpic. Moreover the philosophy behind Friendica pushed me to dig and test the solution

What about you? How do you proceed to broadcast your short messages? Does Friendica offer a good solution in your opinion? Are you interested in the philosophy behind this project? Feel free to share your thoughs in the comments.

LAST MINUTE: hey, this article is on Hacker News, don’t hesitate to vote for it if you liked it!

Nouveau blog entrepreunarial et entreprise propulsée par Debian

april, planet-cullt

Suivez-moi aussi sur Identi.ca ou sur Twitter 

Un petit billet rapide pour parler de l’activité de la société MyTux, spécialisée dans l’infogérance de serveurs Debian (exclusivement), société dont je suis le fondateur. Mais c’est surtout son blog que je souhaite aujourd’hui vous présenter.

logo-infogerance

Quelques exemples d’articles déjà publiés :

Le blog de la société MyTux se concentre sur l’infogérance de serveurs Debian et vise à informer aussi bien les clients de MyTux qu’un public plus large d’utilisateurs de serveurs Debian.

debian-banner

On y parle donc des bonnes pratiques du domaine, des évolutions des versions stables de Debian, et on y parlera de tout ce qui se rapporte aux serveurs de production sous Debian, vu par des professionnels de l’infogérance.

J’espère vous y croiser bientôt :)

My Debian contributions in January 2014

brebis, contributions-debian, debian

Follow me on Identi.ca  or Twitter 

One of my resolutions for 2014 is to keep trying harder to talk about my Debian contributions. So here it is, on a monthly basis this time I hope, quite short this month because I’m leaving for holidays at the end of the week and I think I won’t have time to contribute more this month.

Debian packages

Below are some packages I updated recently:

1. Brebis, the fully automated backup checker

I successively packaged Brebis, the fully automated backup checker, versions 0.6 to 0.9 (the latter is today in Debian Sid and Jessie) since my last Debian activities blog posts (in french).

brebis-brown-big-logo

Anisette, the mascot of the Brebis Project

2. Pycallgraph, a Python library that creates call graphs for Python programs

Pycallgraph is one of the first Debian packages I have been maintaining. So when I noticed it was upgraded after so much time I was really eager to package the new version 1.0.1. Now available in Debian Sid! Just belown an example of the generated graph for the application Belier, a sysadmin tool.

pycallgraph

3. Belier, the SSH connection generation tool

Nothing really new for Belier, the SSH connection generation tool but I updated the package in order to update the configuration of the Debian package and get rid of some warning messages. Kind of maintenance job I kept avoiding and avoiding, until now.

Bug report

I’d like to take a few seconds to talk about an interesting bug report about the need for a nagios3-dev package I created asking for a new nagios3-dev or nagios3-headers package to offer a simple access to the headers of Nagios for the developers of Nagios external modules.

In Nagios, some headers are generated after the ./configure, meaning it may be platform dependent. I (and not only me, the same request was active already by someone other Nagios module developers) thought it was simple to ask the Nagios3 Debian package maintainer to offer these files in a dedicated package.

It seems until now people just add the missing files in tarball of their app or in their Debian packages, even if these Nagios headers are not really part of this application. In my opinion, that’s why Build-Depends packages are for, don’t you think?

nagios

It seems it is not so simple. I could not understand why it was more important to prevent Debian users who need these files to access these files in a convenient way than letting them to put theses files in there own source tarball/repository. The maintainer told me it could break things. Sure. But we all know an external module of any app often relies on a really specific version of this app. That’s nothing new, thats how external modules work. That’s not every apps in the world which could provide a stable API to ease the development of external modules. But at least they give access to their dev files or headers when they are FOSS. But feel free to explain to me. After all, the bug reports are still not tagged as « won’t fix » ;)

Your turn now :)  I’d be delighted to have your opinions in the comments of this blog post.

Virtual environments with Python 3.3

debian, python, sysadmin

Follow me on Identi.ca  or Twitter 

One of the major features of Python 3.3 is the new venv module, allowing the creation of Python virtual environments on your system.

1. What is a virtual environment?

A virtual environment is a directory dedicated to the execution of your Python applications. Activating your virtual environment will force Python to execute in this directory as the top level of this directory was the root of your file system.

The virtual environments are interesting because of the independence they have toward the host they run on, especially when you want to install several versions of Python or if you want to install lots of dependencies without being the system administrator of the host.

python-logo-master-v3-TM

If you are a Python developer, you must know virtualenv. This really nice application offers a nice way to create Python virtual environment. Moreover it comes with pip already installed in your virtual environment, in order to install other dependencies you need in a really convenience way.

Starting from Python 3.3, the module venv of the Python standard library offers the users to create virtual environments. This new feature will encourage all users to create virtual environments to develop their own Python applications, which is a good practice. Thanks to the experiences of several applications being used in the Python community, the module venv was written to be really efficient and widely available.

The Python Enhancement Proposal 405 (PEP405) offers a really interesting reading if you wish to find more information about this topic.

2. Creating a virtual environment with Python 3.3

With Python 3.3 comes pyvenv-3.3, allowing to create Python virtual environment:

$ pyvenv-3.3 myvirtualenv
$ cd myvirtualenv/
$ tree .
.
├── bin
│   ├── activate
│   ├── pydoc
│   ├── python -> python3.3
│   ├── python3 -> python3.3
│   └── python3.3 -> /usr/bin/python3.3
├── include
├── lib
│   └── python3.3
│       └── site-packages
└── pyvenv.cfg

As we can see, three directories were created.

  • bin/ offers the activate script and different links to the executable python3.3
  • lib/ offers a tree of directories where the libraries and packages you install in your virtual environment will be stored
  • include/ is by default empty
  • pyvenv.cfg offers different configuration options
$ cat pyvenv.cfg 
home = /usr/bin
include-system-site-packages = false
version = 3.3.2

Just before moving on, if you want to use the existing modules in your global site-packages directory on your system, the option –system-site-packages is available.

3. Activate the virtual environment

Lets activate our virtual environment. We need to use the bin/activate file in this environment:

$ source bin/activate 
(myvirtualenv) $

A change in our prompt indicated the good activation of the virtual environment.

4. Installing applications in the virtual environment

But playing around with only the default Python interpreter is not really funny. Lets download pip, the Python installer, but before that we need a dependency setuptools:

(myvirtualenv) $ curl https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -o ez_setup.py
 % Total % Received % Xferd Average Speed Time Time Time Current
 Dload Upload Total Spent Left Speed
 100 11356 100 11356 0 0 18507 0 --:--:-- --:--:-- --:--:-- 18495
(myvirtualenv) $ curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py -o get-pip.py
 % Total % Received % Xferd Average Speed Time Time Time Current
 Dload Upload Total Spent Left Speed
 100 543k 100 543k 0 0 685k 0 --:--:-- --:--:-- --:--:-- 685k

Now lets install Setuptools and Pip:

(myvirtualenv) $ python3.3 ez_setup.py
 Downloading https://pypi.python.org/packages/source/s/setuptools/setuptools-2.0.tar.gz
 Extracting in /tmp/tmpxlrv7q
 Now working in /tmp/tmpxlrv7q/setuptools-2.0
 Installing Setuptools
... (lots of lines)...
Installed /tmp/myvirtualenv/lib/python3.3/site-packages/setuptools-2.0-py3.3.egg
 Processing dependencies for setuptools==2.0
 Finished processing dependencies for setuptools==2.0
(myvirtualenv) $ python3.3 get-pip.py
 Downloading/unpacking pip
 Downloading pip-1.4.1.tar.gz (445kB): 445kB downloaded
 Running setup.py egg_info for package pip
 ... (lots of lines)...
 Successfully installed pip
 Cleaning up...

Ok now we’re ready to use pip to install anything we need in our virtual environment. Lets think one more second about what we did: we install the Setuptools and the Pip application inside our virtual environment, with nothing written on our main system. Now lets try to install Brebis, the fully automated backup checker, and run it in this environment:

(myvirtualenv) $ pip-3.3 install brebis
 Downloading/unpacking brebis
 Downloading brebis-0.8.tar.gz
 Running setup.py egg_info for package brebis
Installing collected packages: brebis
 Running setup.py install for brebis
 changing mode of build/scripts-3.3/brebis from 644 to 755
changing mode of /tmp/myvirtualenv/bin/brebis to 755
 Successfully installed brebis
 Cleaning up...

We’re now ready to launch Brebis, executing in our virtual environment:

(myvirtualenv) $ brebis -h
usage: brebis [-h] [-c DIR] [-C DIR] [-d DELIMITER] [-g] [-G] [-l FILE]
 [-L DIR] [-O DIR] [-v] 
Fully automated backup checker
positional arguments:
 archives archives to check
optional arguments:
 -h, --help show this help message and exit
 -c DIR, --configpath DIR
 the path to the configurations
 -C DIR, --output-conf-dir DIR
 the directory to store the configuration file
 -d DELIMITER, --delimiter DELIMITER
 delimiter of the fields for the list of files
 -g, --gen-list generate a list of files inside a backup
 -G, --gen-full generate the configuration file and the list of files
 for the backup
 -l FILE, --log FILE the log file
 -L DIR, --output-list-dir DIR
 the directory to store the list of files inside an
 archive or tree
 -O DIR, --output-list-and-conf-dir DIR
 the directory to store the configuration file and the
 list of files inside an archive or tree
 -v, --version print the version of this program and exit
For more information: http://www.brebisproject.org

So we get an execution of the Brebis application inside our virtual environment, installed from our virtual environment with tools installed only in the virtual environment.

That’s a big step that such a feature is now included in the standard library. In the future, you will enjoy the possibility to create new virtual environments for each Python version right out of the box. Moreover, using the –upgrade option of the pyvenv command, you will upgrade, if needed, your virtual environment in a really easy and straightforward way, making environments adaptable in time.

What about you? What do you think about the Python 3 virtual environments and their features, given your own needs? Feel free to use the comments section of this post.

X-mas present: Brebis 0.9, the fully automated backup checker, released

debian, sysadmin

Follow me also on Twitter 

Just in time for this 2013 Christmas, the Brebis Project released Brebis « Bouddhinette » 0.9. Hope you’ll enjoy our X-mas present ;)

Reminder: Brebis is the fully automated backup checker, a CLI software developed in Python, allowing users to verify the integrity of archives (tar,gz,bz2,lzma,zip) and the state of the files inside the archives. You will find more information about Brebis features on the Brebis Project homepage.

What’s new?

The major features for this release are:

  • support of the apk archive
  • the cli offers new options to store the configuration file (-C), the list of files (-L) or both (-O) in custom locations
brebis-brown-big-logo

Anisette, the proud mascot of the Brebis Project

The extensive list of the supported features is available on the Brebis Project homepage.

Get Brebis

The official archive of Brebis 0.9 is available here.

Feedback about Brebis

What do you think about the Brebis project ? We at the Brebis Project welcome any feedback about Brebis. Feel free to comment on this blog,  to subscribe to the Brebis-users mailing listby Twitter or email me directly at carl.chenet@brebisproject.org

Official website: http://www.brebisproject.org
Mailing-list: http://lists.sourceforge.net/lists/listinfo/brebis-users

Cadeau de Noël : Publication de Brebis 0.9, le vérificateur automatisé de sauvegarde

april, brebis, debian-fr, planet-cullt, planet-libre, python

Suivez-moi aussi sur Identi.ca ou sur Twitter 

Peu de temps avant ce Noël, l’équipe du projet Brebis a publié la version « Bouddhinette » 0.9 du vérificateur automatisé de sauvegardes. Pour rappel, Brebis est un programme en ligne de commande codé en Python permettant le contrôle automatisé de l’intégrité d’archives (tar, gz, bzip2, lzma, zip) et de la cohérence des fichiers à l’intérieur des archives. Au menu de cette version :

  • Support des archives apk
  • Nouvelles options de la ligne de commandes pour écrire le fichier de configuration (-C), la liste des fichiers dans l’archive (-L) ou les deux (-O) dans un répertoire défini par l’utilisateur (où précédemment ces fichiers étaient écrits par défaut dans le même répertoire que l’archive elle-même).
brebis-brown-big-logo

Anisette, la fière nouvelle mascotte et nouveau logo du projet Brebis généreusement contribué par Antoine Millet

Comme annoncé aux JM2L, Brebis continue d’intégrer des nouveaux types d’archives , mais aussi rend sa manipulation plus flexible afin d’être intégré plus simplement pour répondre aux besoins de ses utilisateurs en s’adaptant plus simplement aux différentes situations existantes..

Feedback sur Brebis

Et vous ? Que pensez-vous de Brebis ? N’hésitez pas à vous abonner à la liste de diffusion de Brebis,  à laisser un commentaire ici ou  un message sur le forum ou à me contacter directement, tous les retours seront appréciés.

Retour sur Brebis, le vérificateur automatisé de sauvegarde, aux JM2L

april, debian-fr, planet-cullt, planet-libre, python

Suivez-moi aussi sur Identi.ca ou sur Twitter 

Comme chaque année avait lieu à Sophia Antipolis les Journées Méditerrannéennes du Logiciel Libre, organisées par l’association Linux Azur. J’avais proposé pour cette année une présentation du projet  Brebis, le vérificateur automatisé de sauvegarde. C’était pour moi l’occasion de réaliser quelques slides parlant du projet (désormais disponible en ligne – CC by SA) et de recueillir les réactions du public.

jm2l

L’accueil est chaleureux, comma d’habitude et le public est présent. On m’avait accordé un créneau d’une bonne heure. j’ai donc essayé de captiver mon public pendant 50 minutes avant la séance de questions. La présentation se découpe en deux phases, une introduction au domaine de la sauvegarde et à la nécessité de vérifier les sauvegardes régulièrement, puis une seconde partie plus technique sur les fonctionnalités du logiciel Brebis lui-même.

brebis-brown-big-logo

Anisette, la fière nouvelle mascotte et nouveau logo du projet Brebis généreusement contribué par Antoine Millet

La conférence a été filmée, je pourrai donc vérifier ce qu’il en est une fois que les vidéos seront en ligne.

Niveau stand, les exposants sont accueillants et disponibles et je suis content de voir cet événement du Logiciel Libre toujours aussi fréquenté. Trois fois que je fais le déplacement et je repasse sans faute l’année prochaine !

Étiez-vous aux JM2L aussi ? Qu’en avez-vous pensé ? N’hésitez pas à réagir dans les commentaires de ce billet.

Yarn: a scenario testing tool

debian, sysadmin

Follow me also on Twitter  

Those who follow me on Twitter may have read my recent tweet about Yarn, a really nice software by Lars Wirzenius I discovered the last week-end while attending the Mini-Debconf UK in Cambridge.

To make a long story short, Yarn allows the user to write scenarios of the executions of softwares. This scenario will be automatically played by Yarn which also returns the overview of the execution, with the goal to test the behaviour of these softwares.

1. Small example of how to use Yarn

Let’s have a look of how to use Yarn with a real example. The scenario will test if the software Brebis, a fully automatized backup checker, executes in an expected way. We can proceed as follow :

  1. set up the test environment
  2. launch a command with the software under test in the test environment
  3. verify the execution of the test

This is an example of a Yarn scenario file, the file is formatted using the Markdown syntax:

    SCENARIO basic brebis execution
    GIVEN setting up brebis
    AND generating backup configuration with brebis
    WHEN brebis verifies a backup
    THEN verify brebis output

    IMPLEMENTS GIVEN setting up brebis
    hg clone http://hg.brebisproject.org $DATADIR/brebis
    mkdir -p $DATADIR/brebis/yarn-test
    cp $DATADIR/brebis/functional-tests/expected-generated-list-for-tar-archive/expected-generated-list-for-tar-archive.tar.gz $DATADIR/brebis/yarn-test

    IMPLEMENTS GIVEN generating backup configuration with brebis
    $DATADIR/brebis/brebis.py -G $DATADIR/brebis/yarn-test/expected-generated-list-for-tar-archive.tar.gz

    IMPLEMENTS WHEN brebis verifies a backup
    $DATADIR/brebis/brebis.py -c $DATADIR/brebis/yarn-test -l $DATADIR/brebis/yarn-test/brebis.log

    IMPLEMENTS THEN verify brebis output
    if [ -s $DATADIR/brebis/yarn-test/brebis.log ]; then return 1; else return 0; fi

2. Result of the execution of the Yarn scenario

Yarn provides at the end of the scenario an overview of the execution, as show below:

$ yarn brebis-scenario
Scenario test suite PASS, with 1 scenarios (4 total steps), in 16.4 seconds

3. Details of the Yarn scenarios

The five first lines are basically your scenario. Each step takes a keyword and a sentence to identify a step. You define a name with the SCENARIO keyword. The next step, GIVEN, allows generally the setup of the test environment. It is possible of course to define different steps with the keywork AND.

Once the environment setup has been completed, we launch the test with the keyword WHEN. At last we check the result of the execution with THEN. It is worth noting that if you need further steps after checking the result of the execution, you can use FINALLY.

Very helpful while setting up the test environment is the variable $DATADIR, automatically initialized by Yarn. It provides the path to a temporary directory where you can store files during the execution of your scenario. This directory is by default removed at the end of the scenario.

Now the real trick: at each step I described above is associated shell commands to execute thanks to the IMPLEMENTS keyword.It’s in my opinion a great way to increase the understanding of what the scenario really does. In a short glance of the first lines, if the names of the steps are carefully chosen, you will understand what the scenario does without needing to read the actual shell code. Simple and efficient.

4. More about Yarn

Yarn is written in Python and now available in Debian in the package cmdtest. The sources are available here. In my opinion, if you were looking for this kind of tool, Yarn is in a really good direction. This project is still young but the core features do the job and the upstream is eager to receive feedbacks (and patches) :)

Some links:

Interested in Yarn? What do you think about it? Let us know in the comments of this post.