Preface

Welcome to the Helix Installer Test Suite.

Please Give Us Feedback

Perforce welcomes feedback from our users. Please send any suggestions for improving this document or the SDP to consulting@perforce.com.

1. Overview

The hits.sh script is used to build test machine images on various operating systems, execute tests, and capture and summarize the results.

Overview of the Helix Installer Test Suite hits.sh script:
USAGE for hits.sh v1.4.0:

hits.sh [-B|-b] [-f] [-p] [-o <os1>[,<os2>,...]] [-hb <helix_installer_branch>] [-sb <sdp_branch>] [-n] [-D] [-L <log>]

or

hits.sh [-h|-man]


DESCRIPTION:
	This script manages Docker environment for the Helix Installer Test Suite.

	The test_hi.sh runs the actual tests within VMs managed by this script.

OPTIONS:
 -b	Build Docker images, and then stop before running tests. By default,
 	tests are executed after images are built.

 -f	Specify '-f' to force a rebuild of the Docker image by passing '--no-cache'
 	option to the 'podman build' command.

 -p	Specify '-p' to pull the latest Docker source image by passing '--pull'
 	option to the 'podman build' command.

 -B	Specify '-B' as a shorthand for '-b -f -p'.

 -o	Specify a comma-delimited list of operating systems to build.
 	Valid operating system values are:

	rocky8 rocky9 centos7 ubuntu20 ubuntu22

 -hb <helix_installer_branch>
 	Specify the Helix Installer branch to test.  The default is dev.

 -sb <sdp_branch>
 	Specify the SDP branch to test.  The default is main, which always
	represents the latest version officially released for general
	availability.

 -L <log>
	Specify the path to a log file, or the special value 'off' to disable
	logging.  By default, all output (stdout and stderr) goes to

	hits.<DateTimeStamp>.log

	NOTE: This script is self-logging.  That is, output displayed on the
	screen is simultaneously captured in the log file.  Do not run this
	script with redirection operators like '> log' or '2>&1', and do not
	use 'tee'.

 -si	Operate silently.  All output (stdout and stderr) is redirected to the
 	log only; no output appears on the terminal.  This cannot be used with
	'-L off'.

	This is useful when running from cron, as it prevents automatic email
	from being sent by cron directly, as cron does when a script called
	from cron generates any output.  This script is then responsible for
	email handling, if any is to be done.

 -n	No-Op.  Prints podman, rsync, and other commands instead of running
 	them.

 -D     Set extreme debugging verbosity.

HELP OPTIONS:
 -h	Display short help message
 -man	Display man-style help message

EXAMPLES:
	Example 1: Normal test run on all platforms - no arguments.
	hits.sh

	Example 2: Test image build only
	hits.sh -B

	Example 3: Test on a single platform:
	hits.sh -o centos7

	Example 4: See podman and other commands without executing them.
	hits.sh -n

2. Interacting with the Test Suite

Interact with a command like this:

podman run --rm -v $PWD/hi:/hi -it perforce/rocky9_hi /bin/bash

3. Requirements and One-Time Setup

The podman utility must be installed. Testing has been done with podman v5.0.3. Other versions may work.

Appendix A: Test Suite History

The third and current generation of the Helix Installer Test Suite came online in June, 2024. This replaced Docker with Podman.

The second generation of the Helix Installer Test Suite came online in January, 2021. This used Docker for VM management.

Docker displaced Vagrant-based VM management that had been used in first generation of the test suite from November, 2018 to January, 2021.