# CBD Test Suite

## Getting setup

The test suite is intended to be simple to operate, once the required utilities are installed.  First, install the required software, then execute the test suite.  All are described below.

## Test Suite Requirements

To use this bundle you will need to download and install the following tools, both of which are free.

* Install [Virtual Box](https://www.virtualbox.org/).
* Install [Vagrant](http://vagrantup.com).

The following vagrant plugins are installed with `sudo vagrant plugin-install <plugin_name>`:

* vagrant-vbguest (installs latest VirtualBox Guest additions up to date - important for CentOS!)
* vagrant-hostmanager
* vagrant-cachier

If you're not familiar with Vagrant, it is a command line based virtual machine management tool that makes it easy to create and provision virtual machines, all driven by a simple text file. If you haven't used it before be warned: simple VM management is addictive!

VirtualBox is an open source hypervisor made by Oracle. It runs on many platforms and is the default hypervisor for Vagrant. You do not need to know much of anything about Vagrant to use these tools. We'll explain the few commands you will likely need below.

## Starting the Test Suite

After installing Virtual Box and Vagrant, kick off the test suite like this:

    cd /where/you/put/cbd/test
    vagrant up
    
This command may take a while, perhaps 20 minutes on the first try, while it downloads and provisions the VM, installs the SDP with the Sample Depot using the [Helix Installer](https://swarm.workshop.perforce.com/projects/perforce_software-helix-installer), and ultimately executes the CBD test suite.  The latter step takes only a few seconds at the tail end of the entire process.

## Restarting the Test Suite

After the first run, subsequent start-from-scratch test runs will be faster.  To start from scratch, do:

    vagrant destroy
    vagrant up

To access the VM, e.g. for development and manual testing purposes, do:

    vagrant ssh
    go
    go

The first call to `go` executes as the vagrant user.  It just does a `sudo su - perforce` to change from the user **vagrant** (created by default with Vagrant virtual machines) to the user **perforce** (which operates the Perforce Helix server).

The second call to `go` executes as the **perforce** user.  It sets up the shell environment for manual CBD development and testing.

## Extra Information:  Files in this folder

* **ReadMe.md** - This file.
* **Vagrantfile** - Vagrant file.  This file governs the process started an initial `vagrant up` command is executed, resulting in generation of a virtual machine and execution of the CBD test suite on the new VM.
* **auto_test_cbd.sh** - Test driver script intended to be called from Jenkins or similar.  This hasn't been maintained.
* **auto_test_cbd_vagrant.sh** - Test driver script optimized for operating inside a Vagrant virtual environment.  This is currently the actively used test suite.
* **bootstrap-centos.sh** - This is referenced in the Vagrantfile, and is executed during the `vagrant up` processing.
* **bootstrap-sdp-setup.sh** - Just as with bootstrap-centos.sh is referenced in the Vagrantfile, and is executed during the `vagrant up` processing.
* **get_workshop_cbd.sh** - This script acquires CBD scripts from The Workshop using a p4 clone command.  It is called during initialization of the test VM.  It is called by auto_test_cbd_vagrnat.sh.
* **helix_server.json** - This file defines certain characteristics of the Vagrant virtual machine used for testing.
* **manual_test_env.sh** - This file is sourced by humans in preparation for iterative manual testing, e.g. when developing new features and tests.
* **shared** - This folder contains files that are made available on the Vagrant virtual machine.
* **test_cbd.sh** - This is the primary test driver driver script, which calls all tests in the CBD regression test suite.
* **ti.sh** - A developer utility for testing syntax of some test cases, without actually executing tests.