NAME

App::Dochazka::CLI::Testers - Documentation for volunteer testers

PREREQUISITES

Add zypper repo

Add the home:smithfarm zypper repo for your operating system: http://software.opensuse.org/download.html?project=home%3Asmithfarm&package=perl-App-Dochazka-CLI.

Server installation

Before you start, you will need to install and set up PostgreSQL and the Dochazka REST server. There are two ways to accomplish this: the Docker way and the "traditional" way.

"The Docker way" is arguably simpler, because you don't install as many packages and there is little or no setup work involved. However, quite a lot of data (on the order of hundreds of MB) will be downloaded from Docker Hub. (To handle this, it may be a good idea to put /var/lib/docker on a separate partition.)

"The traditional way" is to install and configure PostgreSQL and the Dochazka REST server in your testing environment. This is somewhat more complicated and involves installing and operating a PostgreSQL server on the machine where you will be running the tests.

Both ways are described below.

The Docker way

Complete the steps described below:

Install Docker

For testing purposes, you can use the Dockerized REST server. For this, you will need to have Docker installed and running:

    zypper install docker
    systemctl start docker.service

Get and run test drive script

The REST server Docker image depends on the official PostgreSQL image and must be run with certain parameters. A script is provided to make this easy. Download and run the script:

    wget https://raw.githubusercontent.com/smithfarm/dochazka-rest/master/test-drive.sh
    sh test-drive.sh

If you have never run Docker containers before, you may be surprised that the script downloads quite a lot of data from Docker Hub. The script should complete without any error messages.

Web browser test

When the test-drive.sh script completes, you should be able to access the REST server by pointing your browser at http://localhost:5000. At the login dialog, enter username "demo" and password "demo".

The traditional way

This way involves taking the same steps as if you were installing a production Dochazka server.

Install server packages

The traditional way assumes that you have the PostgreSQL and Dochazka REST server packages installed:

    zypper install postgresql postgresql-server postgresql-contrib 
    zypper install perl-App-Dochazka-REST 

PostgreSQL setup

Follow the instructions at https://metacpan.org/pod/App::Dochazka::REST::Guide#PostgreSQL-setup.

Site configuration

Follow the instructions at https://metacpan.org/pod/App::Dochazka::REST::Guide#Site-configuration.

Database initialization

Follow the instructions at https://metacpan.org/pod/App::Dochazka::REST::Guide#Database-initialization.

Web browser test

After completing the above, you should be able to access the REST server by pointing your browser at http://localhost:5000. At the login dialog, enter username "demo" and password "demo".

Install Dochazka CLI client

Now that the server part is working, install the CLI:

    zypper install perl-App-Dochazka-CLI

You should now be able to start the CLI and login as "demo" with password "demo":

    $ dochazka-cli -u demo -p demo
    Loading configuration files from
    /usr/lib/perl5/vendor_perl/5.18.2/auto/share/dist/App-Dochazka-CLI
    Cookie jar: /root/.cookies.txt
    URI base http://localhost:5000 set from site configuration
    Authenticating to server at http://localhost:5000 as user root
    Server is alive
    Dochazka(2016-01-12) demo PASSERBY>

Exit the CLI by issuing the exit command:

    Dochazka(2016-01-12) demo PASSERBY> exit
    $

Congratulations! You have passed the first test.

SESSION 1: CREATE AN EMPLOYEE

Try with insufficient privileges

To create an employee, you will need to be logged in as an administrator. The "demo" employee is not an administrator, but let's try anyway. First, log in according to "Verify success", above. Then, issue the employee list command:

    Dochazka(2016-01-12) demo PASSERBY> employee list
    *** Anomaly detected ***
    Status:      403 Forbidden
    Explanation: ACL check failed for resource employee/list/?:priv (ERR)

This output indicates that the REST server returned a 403 Forbidden error, which is to be expected because the demo employee has insufficient privileges.

Next, try to create an employee:

    Dochazka(2016-01-12) demo PASSERBY> PUT employee nick george { "fullname" : "King George III" }
    HTTP status: 403 Forbidden
    Non-suppressed headers: {
      'X-Web-Machine-Trace' => 'b13,b12,b11,b10,b9,b8,b7'
    }
    Response:
    {
       "payload" : {
          "http_code" : 403,
          "uri_path" : "employee/nick/george",
          "permanent" : true,
          "found_in" : {
             "file" : "/usr/lib/perl5/vendor_perl/5.22.0/App/Dochazka/REST/Auth.pm",
             "package" : "App::Dochazka::REST::Auth",
             "line" : 431
          },
          "resource_name" : "employee/nick/:nick",
          "http_method" : "PUT"
       },
       "text" : "ACL check failed for resource employee/nick/:nick",
       "level" : "ERR",
       "code" : "DISPATCH_ACL_CHECK_FAILED"
    }

Here, the error is the same 403 Forbidden but the output is more detailed. This is because we used a special type of command that is ordinarily only used to test the REST API.

Log in as root

For the rest of this session, we will be logged in as the root employee, which has a special status in that it is created when the database is initialized and it is difficult or impossible to delete. In a freshly initialized database, the root employee's password is "immutable".

The username and password need not be specified on the command line. Try it this way:

    $ dochazka-cli
    Loading configuration files from /usr/lib/perl5/vendor_perl/5.18.2/auto/share/dist/App-Dochazka-CLI
    Cookie jar: /root/.cookies.txt
    URI base http://localhost:5000 set from site configuration
    Username: root
    Authenticating to server at http://localhost:5000 as user root
    Password: 
    Server is alive
    Dochazka(2016-01-12) root ADMIN>

List employees

A list of all employees in the database can be obtained using the employee list command, which is documented at App::Dochazka::CLI::Guide:

    Dochazka(2016-01-12) root ADMIN> employee list

    List of employees with priv level ->all<-
        demo
        root

Actually, there is no priv level "all" - this just means that all employees are listed, regardless of their priv level.

You can also try listing employees by priv level as per the documentation.

Create an employee

At the moment there is no CLI command to create a new employee. Hence we use the REST API testing command as described in App::Dochazka::CLI::Guide:

    Dochazka(2016-01-12) root ADMIN> PUT employee nick george { "fullname" : "King George III" }
    HTTP status: 200 OK
    Non-suppressed headers: {
      'X-Web-Machine-Trace' => 'b13,b12,b11,b10,b9,b8,b7,b6,b5,b4,b3,c3,c4,d4,e5,f6,g7,g8,h10,i12,l13,m16,n16,o16,o14,p11,o20,o18,o18b'
    }
    Response:
    {
       "code" : "DOCHAZKA_CUD_OK",
       "count" : 1,
       "payload" : {
          "email" : null,
          "remark" : null,
          "eid" : 3,
          "passhash" : null,
          "supervisor" : null,
          "sec_id" : null,
          "salt" : null,
          "nick" : "george",
          "fullname" : "King George III"
       },
       "text" : "DOCHAZKA_CUD_OK",
       "DBI_return_value" : 1,
       "level" : "OK"
    }

Employee profile

The properties, or attributes, of the employee class can be seen in the output of the previous command (under "payload"). A more comfortable way to display the properties of any employee is the employee profile command:

    Dochazka(2016-01-12) root ADMIN> employee profile

    Full name:    Root Immutable
    Nick:         root
    Email:        root@site.org
    Secondary ID: (not set)
    Dochazka EID: 1
    Reports to:   (not set)

In this form, it displays the profile of the logged-in employee. To show the profile of a different employee, use this form:

    Dochazka(2016-01-12) root ADMIN> emp=demo profile

    Full name:    Demo Employee
    Nick:         demo
    Email:        demo@dochazka.site
    Secondary ID: (not set)
    Dochazka EID: 2
    Reports to:   (not set)

Here, the "emp=demo" is an employee spec. This is explained in "Specify an employee" in App::Dochazka::CLI::Guide.

Finally, try various combinations of the following commands to get information about the new employee you just created:

    employee list
    employee profile
    emp=... profile
    nick=... profile
    eid=... profile

cpanm App::Dochazka::CLI

perl -MCPAN -e shell
install App::Dochazka::CLI