Version:

Tester Guide

/ binnacle / latest / introduction/

Introduction

Binnacle is inspired by the Testing framework used in the GlusterFS project. GlusterFS uses TAP(Test Anything protocol) based test framework. All the tests are written in bash script.

Automating tests in a distributed setup is always hard. Binnacle aims to simplify the ergonomics so that a tester without Programming language expertise can adapt to this quickly.

# file: test_ssh_key_initialized.t
TEST "stat ~/.ssh/id_rsa.pub"

and run the test using,

$ binnacle test_ssh_key_initialized.t
ok       1 - node=local cmd="TEST stat ~/.ssh/id_rsa.pub"


STATUS  TESTS  PASSED  FAILED  DUR(SEC)  SPEED(TPM)  INDEX DUR(SEC)  FILE
=========================================================================
OK          1       1      0          0           0               0

Result: Pass

Use -v for verbose output. Verbose output is compatible with TAP.

$ binnacle test_ssh_key_initialized.t -v
Indexing test files... done.  tests=1  test_files=1  duration_seconds=0


------- STARTED(tests=1, file="test_ssh_key_initialized.t")
ok       1 - node=local cmd="TEST stat ~/.ssh/id_rsa.pub"
------- COMPLETED(OK, tests=1, passed=1, failed=0)


STATUS  TESTS  PASSED  FAILED  DUR(SEC)  SPEED(TPM)  INDEX DUR(SEC)  FILE
=========================================================================
OK          1       1      0          0           0               0  test_ssh_key_initialized.t
-------------------------------------------------------------------------
OK          1       1      0          0           0               0

Result: Pass

Similar to TEST keyword, Binnacle supports many keywords. Read more about supported keywords here.

Multi node support

Easily run all the tests from your laptop that runs tests via ssh or docker exec. Below example shows that hostname is properly set on all the machines.

USE_NODE "node1.example.com"
EXPECT "node1.example.com", "hostname"

USE_NODE "node2.example.com"
EXPECT "node2.example.com", "hostname"

USE_NODE "node3.example.com"
EXPECT "node3.example.com", "hostname"

Default remote plugin is ssh. To use docker plugin,

USE_REMOTE_PLUGIN "docker"

USE_NODE "node1.example.com"
EXPECT "node1.example.com", "hostname"

USE_NODE "node2.example.com"
EXPECT "node2.example.com", "hostname"

USE_NODE "node3.example.com"
EXPECT "node3.example.com", "hostname"

What if we need to set default node to execute all the commands but only a few commands to be executed in another node.

# Default node setup
USE_NODE "node1.example.com"

TEST "stat /var/www/html/index.html"
EXPECT "node1.example.com", "hostname"

USE_NODE "node2.example.com" do
  EXPECT "node2.example.com", "hostname"
end

Remote plugins

When node is selected as non local, then Binnacle uses remote plugin. Default plugin is ssh.

ssh and docker are the supported plugins.

For example,

USE_REMOTE_PLUGIN "ssh"
USE_NODE "node1.example.com"
TEST "command1 arg1 arg2"

Above command will be executed as below when ssh plugin is used.

ssh node1.example.com 'command1 arg1 arg2'
USE_REMOTE_PLUGIN "docker"
USE_NODE "node1.example.com"
TEST "command1 arg1 arg2"

Above command will be executed as below when docker plugin is used.

docker exec -i node1.example.com /bin/bash -c 'command1 arg1 arg2'
© 2021 Kadalu Software Private Limited. All Rights Reserved.