Megatest

(define (assoc/default key lst . default)
  (let ((res (assoc key lst)))
    (if res (cadr res)(if (null? default) #f (car default)))))

(define (common:get-testsuite-name)
  (or (configf:lookup *configdat* "setup" "testsuite" )
      (if *toppath* 
      (pathname-file *toppath*)))
          (pathname-file *toppath*)
          (pathname-file (current-directory)))))

;;======================================================================
;; E X I T   H A N D L I N G
;;======================================================================

(define (common:legacy-sync-recommended)
  (or (args:get-arg "-runtests")

	     (hed     (car inlst))
	     (tal     (cdr inlst)))
    (if (not (null? tal))
	(loop (max hed max-val)
	      (car tal)
	      (cdr tal))
	(max hed max-val))))

;; get min or max, use > for max and < for min, this works around the limits on apply
;;
(define (common:min-max comp lst)
  (if (null? lst)
      #f ;; better than an exception for my needs
      (fold (lambda (a b)
	      (if (comp a b) a b))
	    (car lst)
	    lst)))

;; path list to hash-table tree
;;   ((a b c)(a b d)(e b c)) => ((a (b (d) (c))) (e (b (c))))
;;
(define (common:list->htree lst)
  (let ((resh (make-hash-table)))
    (for-each

					  (lambda ()
					    (if b (dboard:tabdat-target-set! tabdat (string-split b "/")))
					    (dashboard:update-run-command tabdat))
					  "command-testname-selector tb action"))
			      #:value (dboard:test-patt->lines
				       (dboard:tabdat-test-patts-use tabdat))
			      #:expand "HORIZONTAL"
			      ;; #:size "10x30"
			      ))
	 (tb
          (iup:treebox
           #:value 0
           #:name "Runs"
           #:expand "YES"
           #:addexpanded "NO"
           #:size "10x"
           #:selection-cb
           (lambda (obj id state)
             (debug:catch-and-dump
              (lambda ()
                (let* ((run-path (tree:node->path obj id))
                       (run-id    (tree-path->run-id tabdat (cdr run-path))))
                  ;; (dboard:tabdat-view-changed-set! tabdat #t) ;; ?? done below when run-id is a number

                                                        (dboard:graph-dat-flag-set! graph-dat #t)))
                                                    (hash-table-keys (dboard:tabdat-graph-cell-table tabdat))))))
       (iup:hbox
        (iup:button "Hide All" #:action (lambda (obj)
                                          (for-each (lambda (graph-cell)
                                                      (let* ((graph-dat   (hash-table-ref (dboard:tabdat-graph-cell-table tabdat) graph-cell)))
                                                        (dboard:graph-dat-flag-set! graph-dat #f)))
                                                    (hash-table-keys (dboard:tabdat-graph-cell-table tabdat)))))))
                                                    (hash-table-keys (dboard:tabdat-graph-cell-table tabdat)))
                                          (dboard:tabdat-view-changed-set! tabdat #t)))))
      ))))

;;======================================================================
;; R U N
;;======================================================================
;;
;; display and manage a single run at a time

    (iup:show
     (iup:dialog 
      #:title (conc "Megatest dashboard " (current-user-name) ":" *toppath*)
      #:menu (dcommon:main-menu)
      (let* ((runs-view (iup:vbox
			 (iup:split
			  #:orientation "VERTICAL" ;; "HORIZONTAL"
			  #:value 150
			  #:value 200
			  (dboard:runs-tree-browser commondat runs-dat)
			  (iup:split
			   ;; left most block, including row names
			   (apply iup:vbox lftlst)
			   ;; right hand block, including cells
			   (iup:vbox
			    ;; the header
			    (apply iup:hbox (reverse hdrlst))
			    (apply iup:hbox (reverse bdylst)))))
                           (iup:split
                            ;; left most block, including row names
                            (apply iup:vbox lftlst)
                            ;; right hand block, including cells
                            (iup:vbox
                             ;; the header
                             (apply iup:hbox (reverse hdrlst))
                             (apply iup:hbox (reverse bdylst)))))
			 controls
			 ))
	     (views-cfgdat (common:load-views-config))
	     (additional-tabnames '())
	     (tab-start-num       5)   ;; DON'T FORGET TO UPDATE THIS WHEN CHANGING THE STANDARD TABS BELOW
	     ;; (data (dboard:tabdat-init (make-d:data)))
	     (additional-views 	;; process views-dat

(define (dashboard:get-youngest-run-db-mod-time tabdat)
  (handle-exceptions
   exn
   (begin
     (debug:print 0 *default-log-port* "WARNING: error in accessing databases in get-youngest-run-db-mod-time: " ((condition-property-accessor 'exn 'message) exn))
     (current-seconds)) ;; something went wrong - just print an error and return current-seconds
   (apply max (map (lambda (filen)
   (common:max (map (lambda (filen)
		     (file-modification-time filen))
		   (glob (conc (dboard:tabdat-dbdir tabdat) "/*.db"))))))

(define (dashboard:monitor-changed? commondat tabdat)
  (let* ((run-update-time (current-seconds))
	 (monitor-db-path (dboard:tabdat-monitor-db-path tabdat))
	 (monitor-modtime (if (and monitor-db-path (file-exists? monitor-db-path))

    (hash-table-set! rowhash 
		     (+ i rownum)
		     (cons (cons x1 x2) 
			   (hash-table-ref/default rowhash (+ i rownum) '())))
    (if (< i num-rows)
	(loop (+ i 1)))))

;; get min or max, use > for max and < for min, this works around the limits on apply
;;
(define (dboard:min-max comp lst)
  (if (null? lst)
      #f ;; better than an exception for my needs
      (fold (lambda (a b)
	      (if (comp a b) a b))
	    (car lst)
	    lst)))

;; sort a list of test-ids by the event _time using a hash table of id => testdat
;;
(define-inline (dboard:sort-testsdat-by-event-time test-ids tests-ht)
  (sort test-ids
	(lambda (a b)
	  (< (db:test-get-event_time (hash-table-ref tests-ht a))
	     (db:test-get-event_time (hash-table-ref tests-ht b))))))

                                   (list? (dboard:tabdat-target tabdat))
                                   (not (null? (dboard:tabdat-target tabdat))))
                              (last (dboard:tabdat-target tabdat))
                              "%"))
	       (testpatt  (or (dboard:tabdat-test-patts tabdat) "%"))
	       (filtrstr  (conc targpatt "/" runpatt "/" testpatt)))
	  ;; (print "targpatt: " targpatt " runpatt: " runpatt " testpatt: " testpatt)
          (print "RA => dboard:tabdat-last-filter-str " dboard:tabdat-last-filter-str "filtrstr" filtrstr "dboard:tabdat-view-changed" (dboard:tabdat-view-changed tabdat))

	  (if (not (equal? (dboard:tabdat-last-filter-str tabdat) filtrstr))
	  (if (or (not (equal? (dboard:tabdat-last-filter-str tabdat) filtrstr))
                  (dboard:tabdat-view-changed tabdat))
	      (let ((dwg (dboard:tabdat-drawing tabdat)))
		(print "reseting drawing")
		(dboard:tabdat-layout-update-ok-set! tabdat #f)
		(vg:drawing-libs-set! dwg (make-hash-table))
		(vg:drawing-insts-set! dwg (make-hash-table))
		(vg:drawing-cache-set! dwg '())
		(dboard:tabdat-allruns-by-id-set! tabdat (make-hash-table))

    (if (and cnv dwg vch)
	(begin
	  (vg:drawing-xoff-set! dwg (dboard:tabdat-xadj tabdat))
	  (vg:drawing-yoff-set! dwg (dboard:tabdat-yadj tabdat))
	  (mutex-lock! mtx)
	  (canvas-clear! cnv)
	  (vg:draw dwg tabdat)
          ;; RA => (dashboard:run-times-tab-run-data-updater commondat tabdat tab-num)
	  (mutex-unlock! mtx)
          (print "RA => View changed found to be set" )
	  (dboard:tabdat-view-changed-set! tabdat #f)))))
  
;; doesn't work.
;;
;;(define (gotoescape tabdat escape)
;;  (or (dboard:tabdat-layout-update-ok tabdat)
;;      (escape #t)))

					      (dboard:rundat-hierdat rundat)))
			       (tests-ht  (dboard:rundat-tests rundat))
			       (all-tids  (hash-table-keys   tests-ht)) ;; (apply append hierdat)) ;; was testsdat
			       (testsdat  (hash-table-values tests-ht))
			       (runcomp   (vg:comp-new));; new component for this run
			       (rows-used (make-hash-table)) ;; keep track of what parts of the rows are used here row1 = (obj1 obj2 ...)
			       ;; (row-height 4)
			       (run-start  (dboard:min-max < (map db:test-get-event_time testsdat)))
			       (run-end    (let ((re (dboard:min-max > (map (lambda (t)(+ (db:test-get-event_time t)(db:test-get-run_duration t))) testsdat))))
			       (run-start  (common:min-max < (map db:test-get-event_time testsdat)))
			       (run-end    (let ((re (common:min-max > (map (lambda (t)(+ (db:test-get-event_time t)(db:test-get-run_duration t))) testsdat))))
					     (max re (+ 1 run-start)))) ;; use run-start+1 if run-start == run-end so delta is not zero
			       (timeoffset (- run-start)) ;; (+ fixed-originx canvas-margin) run-start))
			       (run-duration (- run-end run-start))
			       (timescale  (/ (- sizex (* 2 canvas-margin))
					      (if (> run-duration 0)
						  run-duration
						  (current-seconds)))) ;; a least lously guess

				  ;; (iup:attribute-set! tb (conc "COLOR" node-num) color)
				  )
				(hash-table-set! (dboard:tabdat-path-test-ids data) test-path test-id)
				(if (not rownum)
				    (let ((rownums (hash-table-values testname-to-row)))
				      (set! rownum (if (null? rownums)
						       1
						       (+ 1 (apply max rownums))))
						       (+ 1 (common:max rownums))))
				      (hash-table-set! testname-to-row fullname rownum)
				      ;; create the label
				      (set! changed (dcommon:modifiy-if-different 
						     (dboard:tabdat-runs-matrix data)
						     (conc rownum ":" 0)
						     dispname
						     changed))

(define (dcommon:runsdat-get-col-num dat target runname force-set)
  (let* ((runs-index (dboard:runsdat-runs-index dat))
	 (col-name   (conc target "/" runname))
	 (res        (hash-table-ref/default runs-index col-name #f)))
    (if res
	res
	(if force-set
	    (let ((max-col-num (+ 1 (apply max -1 (hash-table-values runs-index)))))
	    (let ((max-col-num (+ 1 (common:max (cons-1 (hash-table-values runs-index))))))
	      (hash-table-set! runs-index col-name max-col-num)
	      max-col-num)))))

(define (dcommon:runsdat-get-row-num dat testname itempath force-set)
  (let* ((tests-index (dboard:runsdat-runs-index dat))
	 (row-name    (conc testname "/" itempath))
	 (res         (hash-table-ref/default runs-index row-name #f)))
    (if res
	res
	(if force-set
	    (let ((max-row-num (+ 1 (apply max -1 (hash-table-values tests-index)))))
	    (let ((max-row-num (+ 1 (common:max (cons -1 (hash-table-values tests-index))))))
	      (hash-table-set! runs-index row-name max-row-num)
	      max-row-num)))))

(define (dcommon:rundat-copy-tests-to-by-name rundat)
  (let ((src-ht (dboard:rundat-tests rundat))
	(trg-ht (dboard:rundat-tests-by-name rundat)))
    (if (and (hash-table? src-ht)(hash-table? trg-ht))

	 (changed      #f)
	 (stats-updater (lambda ()
			 (if (dashboard:database-changed? commondat tabdat context-key: 'run-stats)
			     (let* ((run-stats    (rmt:get-run-stats))
				    (indices      (common:sparse-list-generate-index run-stats)) ;;  proc: set-cell))
				    (row-indices  (car indices))
				    (col-indices  (cadr indices))
				    (max-row      (if (null? row-indices) 1 (apply max (map cadr row-indices))))
				    (max-row      (if (null? row-indices) 1 (common:max (map cadr row-indices))))
				    (max-col      (if (null? col-indices) 1 
						      (apply max (map cadr col-indices))))
						      (common:max (map cadr col-indices))))
				    (max-visible  (max (- (dboard:tabdat-num-tests tabdat) 15) 3))
				    (max-col-vis  (if (> max-col 10) 10 max-col))
				    (numrows      1)
				    (numcols      1))
			       (iup:attribute-set! stats-matrix "CLEARVALUE" "CONTENTS")
			       (iup:attribute-set! stats-matrix "NUMCOL" max-col )
			       (iup:attribute-set! stats-matrix "NUMLIN" (if (< max-row max-visible) max-visible max-row)) ;; min of 20

# design_spec.html : $(SRCFILES) $(CSVFILES)
#         asciidoc -b html5 -a icons -a iconsdir=$(DISPATH)/images/icons -a toc2 design_spec.txt
#

all : server.ps megatest_manual.html client.ps complex-itemmap.png

megatest_manual.html : megatest_manual.txt getting_started.txt writing_tests.txt reference.txt ../plan.txt howto.txt *png
megatest_manual.html : megatest_manual.txt getting_started.txt writing_tests.txt reference.txt ../plan.txt howto.txt installation.txt *png
	asciidoc  -b html5 -a icons -a iconsdir=$(DISPATH)/images/icons -a toc2 megatest_manual.txt
#	dos2unix megatest_manual.html

megatest.pdf : megatest_manual.txt getting_started.txt writing_tests.txt reference.txt ../plan.txt howto.txt *png
	a2x -a toc -f pdf megatest_manual.txt

server.ps : server.dot

Getting Started
===============
---------------

[partintro]
.Getting started with Megatest
--
How to install Megatest and set it up for running your regressions and continuous integration process.
Creating a testsuite or flow and your first test or task.
--

Installation
After installing Megatest you can create a flow or testsuite and add some
------------
tests using the helpers. Here is a quickstart sequence to get you up and
running your first automated testsuite.

Dependencies
~~~~~~~~~~~~
Creating a Megatest Area
~~~~~~~~~~~~~~~~~~~~~~~~

Chicken scheme and a number of "eggs" are required for building
Megatest. See the script installall.sch in the utils directory of the
distribution for a mostly automated way to install everything needed
for building Megatest on Linux.
Choose Target Keys
^^^^^^^^^^^^^^^^^^

First choose your "target" keys. These are used to organise your runs in a
way that is meaningful to your project. If you are unsure about what to use
for keys just use a single generic key such as "RUNTYPE". These keys will be
used to hand values to your tests via environment variables so ensure they
are unique. Prefixing them with something such as PROJKEYS_ is a good
strategy. 

footnote:[An example footnote.]
indexterm:[Example index entry]
Examples of keys:

// 
// 
// And now for something completely different: ((monkeys)), lions and
// tigers (Bengal and Siberian) using the alternative syntax index
// entries.
// (((Big cats,Lions)))
// (((Big cats,Tigers,Bengal Tiger)))
// (((Big cats,Tigers,Siberian Tiger)))
// Note that multi-entry terms generate separate index entries.
// 
// Here are a couple of image examples: an image:images/smallnew.png[]
// example inline image followed by an example block image:
// 
// .Tiger block image
// image::images/tiger.png[Tiger image]
// 
// Followed by an example table:
// 
// .An example table
// [width="60%",options="header"]
// |==============================================
// | Option          | Description
.Example keys
[width="60%",options="header"]
|==============================================
| Option            | Description
// | -a 'USER GROUP' | Add 'USER' to 'GROUP'.
// | -R 'GROUP'      | Disables access to 'GROUP'.
// |==============================================
// 
// .An example example
| RELEASE/ITERATION | This example is used by Megatest for its internal QA.
// ===============================================
// Lorum ipum...
// ===============================================
// 
| ARCH/OS/RELEASE   | For a software project targeting multiple platforms
| UCTRLR/NODETYPE   | Microcontroller project with different controllers
running same software
|==============================================

// [[X1]]
// Sub-section with Anchor
// ~~~~~~~~~~~~~~~~~~~~~~~
// Sub-section at level 2.
// 
// Chapter Sub-section
// ^^^^^^^^^^^^^^^^^^^
// Sub-section at level 3.
// 
// Chapter Sub-section
Create Area Config Files
^^^^^^^^^^^^^^^^^^^^^^^^

You will need to choose locations for your runs (the data generated every
time you run the testsuite) and link tree. For getting started answer the
prompts with "runs" and "links". We use the Unix editor "vi" in the examples
below but you can use any plain text editor.

.Using the helper to create a Megatest area
------------------
megatest -create-megatest-area

// +++++++++++++++++++
// Sub-section at level 4.
# optional: verify that the settings are ok
// 
// This is the maximum sub-section depth supported by the distributed
// AsciiDoc configuration.
vi megatest.config
// footnote:[A second example footnote.]
// 
// 
// The Second Chapter
// ------------------
// An example link to anchor at start of the <<X1,first sub-section>>.
// indexterm:[Second example index entry]
// 
// An example link to a bibliography entry <<taoup>>.
// 
// 
vi runconfigs.config
------------------

Creating a Test
~~~~~~~~~~~~~~~

Choose the test name for your first test and run the helper. You can edit
the files after the initial creation. You will need to enter names and
scripts for the steps to be run and then edit the
tests/<testname>/testconfig file and modify the logpro rules to properly
process the log output from your steps. For your first test just hit enter
for the "waiton", "priority" and iteration variable prompts.

Hint: for geting started make your logpro rules very liberal. expect:error
patterns should match nothing and comment out expect:required rules.

.Using the helper to create a Megatest test
---------------
megatest -create-test myfirsttest

# then edit the generated config
vi tests/myfirsttest/testconfig
---------------

Running your test
~~~~~~~~~~~~~~~~~

First choose a target and runname. If you have a two-place target such as
RELEASE/ITERATION a target would look like v1.0/aff3 where v1.0 is the
RELEASE and aff3 is the ITERATION. For a run name just use something like
run1. 

.Running all tests (testpatt of "%" matches all tests)
---------------
megatest -run -target v1.0/aff3 -runname run1 -testpatt % -log run1.log
---------------

Viewing the results
~~~~~~~~~~~~~~~~~~~

Start the dashboard and browse your run in the "Runs" tab.

.Starting dashboard
----------------
dashboard -rows 24
----------------

How To Do Things
================
----------------

Process Runs
------------
~~~~~~~~~~~~

Remove Runs
~~~~~~~~~~~
^^^^^^^^^^^

From the dashboard click on the button (PASS/FAIL...) for one of the tests. From the test control panel that 
comes up push the clean test button. The command field will be prefilled with a template command for removing 
that test. You can edit the command, for example change the argument to -testpatt to "%" to remove all tests.

.Remove the test diskperf and all it's items
----------------
megatest -remove-runs -target ubuntu/nfs/none -runname ww28.1a -testpatt diskperf/% -v
----------------

.Remove all tests for all runs and all targets
----------------
megatest -remove-runs -target %/%/% -runname % -testpatt % -v
----------------

Archive Runs
~~~~~~~~~~~~
^^^^^^^^^^^^

Megatest supports using the bup backup tool (https://bup.github.io/) to archive your tests for efficient storage
and retrieval. Archived data can be rapidly retrieved if needed. The metadata for the run (PASS/FAIL status, run 
durations, time stamps etc.) are all preserved in the megatest database.

For setup information see the Archiving topic in the reference section of this manual.

To Archive
^^^^^^^^^^
++++++++++

Hint: use the test control panel to create a template command by pushing the "Archive Tests" button.

.Archive a full run
----------------
megatest -target ubuntu/nfs/none -runname ww28.1a -archive save-remove -testpatt %
----------------

To Restore
^^^^^^^^^^
++++++++++

.Retrieve a single test
----------------
megatest -target ubuntu/nfs/none -runname ww28.1a -archive restore -testpatt diskperf/%
----------------

Hint: You can browse the archive using bup commands directly.

launcher bsub
# if defined and not "no" flexi-launcher will bypass launcher unless there is no
# match.
flexi-launcher yes
------------------------

Tricks
======
------

This section is a compendium of a various useful tricks for debugging,
configuring and generally getting the most out of Megatest.

Limiting your running jobs
--------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~

The following example will limit a test in the jobgroup "group1" to no more than 10 tests simultaneously.

In your testconfig:

----------------
[test_meta]
jobgroup group1
----------------

In your megatest.config:

---------------
[jobgroups]
group1 10
custdes 4
---------------




Debugging Tricks
----------------

Examining The Environment
~~~~~~~~~~~~~~~~~~~~~~~~~

Installation
------------

Dependencies
~~~~~~~~~~~~

Chicken scheme and a number of "eggs" are required for building
Megatest. See the script installall.sh in the utils directory of the
source distribution for an automated way to install everything
needed for building Megatest on Linux.

<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="AsciiDoc 8.6.9">
<meta name="generator" content="AsciiDoc 8.6.7">
<title>The Megatest Users Manual</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

/* Default font. */
body {
  font-family: Georgia,serif;

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

.monospaced, code, pre {
pre {
  font-family: "Courier New", Courier, monospace;
  font-size: inherit;
  color: navy;
  padding: 0;
  margin: 0;
}
pre {
  white-space: pre-wrap;
}

#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
#email {

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; vertical-align: text-bottom; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {

div.unbreakable { page-break-inside: avoid; }


/*
 * xhtml11 specific
 *
 * */

tt {
  font-family: "Courier New", Courier, monospace;
  font-size: inherit;
  color: navy;
}

div.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.tableblock > table {
  border: 3px solid #527bbd;

}


/*
 * html5 specific
 *
 * */

.monospaced {
  font-family: "Courier New", Courier, monospace;
  font-size: inherit;
  color: navy;
}

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;

body.manpage div.sectionbody {
  margin-left: 3em;
}

@media print {
  body.manpage div#toc { display: none; }
}


@media screen {
  body {
    max-width: 50em; /* approximately 80 characters wide */
    margin-left: 16em;
  }

  #toc {

</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_preface">Preface</h2>
<div class="sectionbody">
<div class="paragraph"><p>This book is organised as three sub-books; getting started, writing tests and reference.</p></div>
</div>
</div>
<div class="sect2">
<h3 id="_why_megatest">Why Megatest?</h3>
<div class="sect1">
<h2 id="_why_megatest">Why Megatest?</h2>
<div class="sectionbody">
<div class="paragraph"><p>The Megatest project was started for two reasons, the first was an
immediate and pressing need for a generalized tool to manage a suite
of regression tests and the second was the fact that the author had
written or maintained several such tools at different companies over
the years and it seemed a good thing to have a single open source
tool, flexible enough to meet the needs of any team doing continuous
integrating and or running a complex suite of tests for release
qualification.</p></div>
</div>
</div>
<div class="sect2">
<h3 id="_megatest_design_philosophy">Megatest Design Philosophy</h3>
<div class="sect1">
<h2 id="_megatest_design_philosophy">Megatest Design Philosophy</h2>
<div class="sectionbody">
<div class="paragraph"><p>Megatest is intended to provide the minimum needed resources to make
writing a suite of tests and tasks for implementing continuous build
for software, design engineering or process control (via owlfs for
example) without being specialized for any specific problem
space. Megatest in of itself does not know what constitutes a PASS or
FAIL of a test or task. In most cases megatest is best used in
conjunction with logpro or a similar tool to parse, analyze and decide

<li>
<p>
Deployable - anyone on the team, at any site, at any time can run the flow
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect2">
<h3 id="_megatest_architecture">Megatest Architecture</h3>
<div class="sect1">
<h2 id="_megatest_architecture">Megatest Architecture</h2>
<div class="sectionbody">
<div class="paragraph"><p>All data to specify the tests and configure the system is stored in
plain text files. All system state is stored in an sqlite3
database. Tests are launched using the launching system available for
the distributed compute platform in use. A template script is provided
which can launch jobs on local and remote Linux hosts. Currently
megatest uses the network filesystem to call home to your master
sqlite3 database.</p></div>
</div>
</div>
</div>
<h1 id="_road_map">Road Map</h1>
<div class="paragraph"><p>Note 1: This road-map is tentative and subject to change without notice.</p></div>
<div class="paragraph"><p>Note 2: Starting over. Old plan is commented out.</p></div>
<div class="sect1">
<h2 id="_current_items">Current Items</h2>
<div class="sectionbody">
<div class="sect1">
<h2 id="_road_map">Road Map</h2>
<div class="sectionbody">
<div class="paragraph"><p>Note 1: This road-map is still evolving and subject to change without notice.</p></div>
<div class="sect2">
<h3 id="_architecture_refactor">Architecture Refactor</h3>
<div class="sect3">
<h4 id="_goals">Goals</h4>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Reduce load on the file system. Sqlite3 files on network filesystem can be
  a burden.
</p>
</li>
<li>
<p>
Reduce number of servers and frequency of start/stop. This is mostly an
  issue of clutter but also a reduction in "moving parts".
</p>
</li>
<li>
<p>
Coalesce activities to a single home host where possible. Give the user
  feedback that they have started the dashboard on a host other than the
  home host.
</p>
</li>
<li>
<p>
Reduce number of processes involved in managing running tests.
</p>
</li>
</ol></div>
</div>
<div class="sect3">
<h4 id="_changes_needed">Changes Needed</h4>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
ACID compliant db will be on /tmp and synced to megatest.db with a five
  second max delay.
</p>
</li>
<li>
<p>
Read/writes to db for processes on homehost will go direct to /tmp
  megatest.db file.
</p>
</li>
<li>
<p>
Read/wites fron non-homehost processes will go through one server. Bulk
  reads (e.g. for dashboard or list-runs) will be cached on the current host
  in /tmp and synced from the home megatest.db in the testsuite area.
</p>
</li>
<li>
<p>
Db syncs rely on the target db file timestame minus some margin.
</p>
</li>
<li>
<p>
Since bulk reads do not use the server we can switch to simple RPC for the
  network transport.
</p>
</li>
<li>
<p>
Test running manager process extended to manage multiple running tests.
</p>
</li>
</ol></div>
</div>
</div>
<div class="sect2">
<h3 id="_current_items">Current Items</h3>
<div class="sect3">
<h3 id="_ww05_migrate_to_inmem_db">ww05 - migrate to inmem-db</h3>
<h4 id="_ww05_migrate_to_inmem_db">ww05 - migrate to inmem-db</h4>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Switch to inmem db with fast sync to on disk db&#8217;s [DONE]
</p>
</li>
<li>

<p>
Task table used for queueing runner actions (remove runs, cleanRunExecute, etc)
</p>
</li>
</ol></div>
</li>
</ol></div>
<div class="paragraph"><p>shifting, note that the preceding blank line is needed.</p></div>
</div>
</div>
</div>
<h1 id="_getting_started">Getting Started</h1>
<div class="openblock">
<div class="title">Getting started with Megatest</div>
<div class="content">
<div class="paragraph"><p>How to install Megatest and set it up for running your regressions and continuous integration process.</p></div>
</div></div>
</div>
<div class="sect1">
<h2 id="_installation">Installation</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_dependencies">Dependencies</h3>
<div class="paragraph"><p>Chicken scheme and a number of "eggs" are required for building
Megatest. See the script installall.sch in the utils directory of the
distribution for a mostly automated way to install everything needed
for building Megatest on Linux.</p></div>
<div class="paragraph"><p><span class="footnote"><br>[An example footnote.]<br></span></p></div>
Megatest. See the script installall.sh in the utils directory of the
source distribution for an automated way to install everything
needed for building Megatest on Linux.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_getting_started">Getting Started</h2>
<div class="sectionbody">
<div class="openblock">
<div class="title">Getting started with Megatest</div>
<div class="content">
<div class="paragraph"><p>Creating a testsuite or flow and your first test or task.</p></div>
</div></div>
<div class="paragraph"><p>After installing Megatest you can create a flow or testsuite and add some
tests using the helpers. Here is a quickstart sequence to get you up and
running your first automated testsuite.</p></div>
<div class="sect2">
<h3 id="_creating_a_megatest_area">Creating a Megatest Area</h3>
<div class="sect3">
<h4 id="_choose_target_keys">Choose Target Keys</h4>
<div class="paragraph"><p>First choose your "target" keys. These are used to organise your runs in a
way that is meaningful to your project. If you are unsure about what to use
for keys just use a single generic key such as "RUNTYPE". These keys will be
used to hand values to your tests via environment variables so ensure they
are unique. Prefixing them with something such as PROJKEYS_ is a good
strategy.</p></div>
<div class="paragraph"><p>Examples of keys:</p></div>
<table class="tableblock frame-all grid-all"
style="
width:60%;
">
<caption class="title">Table 1. Example keys</caption>
<col style="width:50%;">
<col style="width:50%;">
<thead>
<tr>
<th class="tableblock halign-left valign-top" > Option            </th>
<th class="tableblock halign-left valign-top" > Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top" ><p class="tableblock">RELEASE/ITERATION</p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock">This example is used by Megatest for its internal QA.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" ><p class="tableblock">ARCH/OS/RELEASE</p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock">For a software project targeting multiple platforms</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" ><p class="tableblock">UCTRLR/NODETYPE</p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock">Microcontroller project with different controllers
running same software</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="_create_area_config_files">Create Area Config Files</h4>
<div class="paragraph"><p>You will need to choose locations for your runs (the data generated every
time you run the testsuite) and link tree. For getting started answer the
prompts with "runs" and "links". We use the Unix editor "vi" in the examples
below but you can use any plain text editor.</p></div>
<div class="listingblock">
<div class="title">Using the helper to create a Megatest area</div>
<div class="content monospaced">
<pre>megatest -create-megatest-area

# optional: verify that the settings are ok
vi megatest.config
vi runconfigs.config</pre>
</div></div>
</div>
</div>
<div class="sect2">
<h3 id="_creating_a_test">Creating a Test</h3>
<div class="paragraph"><p>Choose the test name for your first test and run the helper. You can edit
the files after the initial creation. You will need to enter names and
scripts for the steps to be run and then edit the
tests/&lt;testname&gt;/testconfig file and modify the logpro rules to properly
process the log output from your steps. For your first test just hit enter
for the "waiton", "priority" and iteration variable prompts.</p></div>
<div class="paragraph"><p>Hint: for geting started make your logpro rules very liberal. expect:error
patterns should match nothing and comment out expect:required rules.</p></div>
<div class="listingblock">
<div class="title">Using the helper to create a Megatest test</div>
<div class="content monospaced">
<pre>megatest -create-test myfirsttest

# then edit the generated config
vi tests/myfirsttest/testconfig</pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_running_your_test">Running your test</h3>
<div class="paragraph"><p>First choose a target and runname. If you have a two-place target such as
RELEASE/ITERATION a target would look like v1.0/aff3 where v1.0 is the
RELEASE and aff3 is the ITERATION. For a run name just use something like
run1.</p></div>
<div class="listingblock">
<div class="title">Running all tests (testpatt of "%" matches all tests)</div>
<div class="content monospaced">
<pre>megatest -run -target v1.0/aff3 -runname run1 -testpatt % -log run1.log</pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_viewing_the_results">Viewing the results</h3>
<div class="paragraph"><p>Start the dashboard and browse your run in the "Runs" tab.</p></div>
<div class="listingblock">
<div class="title">Starting dashboard</div>
<div class="content monospaced">
<pre>dashboard -rows 24</pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_writing_tests">Writing Tests</h2>
<div class="sectionbody">
<div class="sect2">

</div></div>
<div class="paragraph"><p>This test runs a single step called "stepname1" which runs a script
"stepname.sh". Note that although it is common to put the actions
needed for a test step into a script it is not necessary.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h1 id="_how_to_do_things">How To Do Things</h1>
<div class="sect1">
<h2 id="_how_to_do_things">How To Do Things</h2>
<div class="sectionbody">
<h2 id="_process_runs">Process Runs</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_remove_runs">Remove Runs</h3>
<div class="sect2">
<h3 id="_process_runs">Process Runs</h3>
<div class="sect3">
<h4 id="_remove_runs">Remove Runs</h4>
<div class="paragraph"><p>From the dashboard click on the button (PASS/FAIL&#8230;) for one of the tests. From the test control panel that
comes up push the clean test button. The command field will be prefilled with a template command for removing
that test. You can edit the command, for example change the argument to -testpatt to "%" to remove all tests.</p></div>
<div class="listingblock">
<div class="title">Remove the test diskperf and all it&#8217;s items</div>
<div class="content monospaced">
<pre>megatest -remove-runs -target ubuntu/nfs/none -runname ww28.1a -testpatt diskperf/% -v</pre>
</div></div>
<div class="listingblock">
<div class="title">Remove all tests for all runs and all targets</div>
<div class="content monospaced">
<pre>megatest -remove-runs -target %/%/% -runname % -testpatt % -v</pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_archive_runs">Archive Runs</h3>
<div class="sect3">
<h4 id="_archive_runs">Archive Runs</h4>
<div class="paragraph"><p>Megatest supports using the bup backup tool (<a href="https://bup.github.io/">https://bup.github.io/</a>) to archive your tests for efficient storage
and retrieval. Archived data can be rapidly retrieved if needed. The metadata for the run (PASS/FAIL status, run
durations, time stamps etc.) are all preserved in the megatest database.</p></div>
<div class="paragraph"><p>For setup information see the Archiving topic in the reference section of this manual.</p></div>
<div class="sect3">
<h4 id="_to_archive">To Archive</h4>
<div class="sect4">
<h5 id="_to_archive">To Archive</h5>
<div class="paragraph"><p>Hint: use the test control panel to create a template command by pushing the "Archive Tests" button.</p></div>
<div class="listingblock">
<div class="title">Archive a full run</div>
<div class="content monospaced">
<pre>megatest -target ubuntu/nfs/none -runname ww28.1a -archive save-remove -testpatt %</pre>
</div></div>
</div>
<div class="sect3">
<h4 id="_to_restore">To Restore</h4>
<div class="sect4">
<h5 id="_to_restore">To Restore</h5>
<div class="listingblock">
<div class="title">Retrieve a single test</div>
<div class="content monospaced">
<pre>megatest -target ubuntu/nfs/none -runname ww28.1a -archive restore -testpatt diskperf/%</pre>
</div></div>
<div class="paragraph"><p>Hint: You can browse the archive using bup commands directly.</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>bup -d /path/to/bup/archive ftp</pre>
</div></div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_submit_jobs_to_host_types_based_on_test_name">Submit jobs to Host Types based on Test Name</h3>
<div class="listingblock">
<div class="title">In megatest.config</div>
<div class="content monospaced">

# if defined and not "no" flexi-launcher will bypass launcher unless there is no
# match.
flexi-launcher yes</pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h1 id="_tricks">Tricks</h1>
<h2 id="_tricks">Tricks</h2>
<div class="sectionbody">
<div class="paragraph"><p>This section is a compendium of a various useful tricks for debugging,
configuring and generally getting the most out of Megatest.</p></div>
<div class="sect1">
<h2 id="_limiting_your_running_jobs">Limiting your running jobs</h2>
<div class="sect2">
<h3 id="_limiting_your_running_jobs">Limiting your running jobs</h3>
<div class="sectionbody">
<div class="paragraph"><p>The following example will limit a test in the jobgroup "group1" to no more than 10 tests simultaneously.</p></div>
<div class="paragraph"><p>In your testconfig:</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>[test_meta]
jobgroup group1</pre>
</div></div>
<div class="paragraph"><p>In your megatest.config:</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>[jobgroups]
group1 10
custdes 4</pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_debugging_tricks">Debugging Tricks</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_examining_the_environment">Examining The Environment</h3>

<pre>sudo lsof -i
sudo netstat -lptu
sudo netstat -tulpn</pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h1 id="_reference">Reference</h1>
<div class="sect1">
<h2 id="_megatest_config_file_settings">Megatest Config File Settings</h2>
<div class="sectionbody">
<h2 id="_reference">Reference</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_megatest_config_file_settings">Megatest Config File Settings</h3>
<div class="sect3">
<div class="sect2">
<h3 id="_disk_space_checks">Disk Space Checks</h3>
<h4 id="_disk_space_checks">Disk Space Checks</h4>
<div class="paragraph"><p>Some parameters you can put in the [setup] section of megatest.config:</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre># minimum space required in a run disk
minspace 10000000

# minimum space required in dbdir:
dbdir-space-required 100000

# script that takes path as parameter and returns number of bytes available:
free-space-script check-space.sh</pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_trim_trailing_spaces">Trim trailing spaces</h3>
<div class="sect3">
<h4 id="_trim_trailing_spaces">Trim trailing spaces</h4>
<div class="listingblock">
<div class="content monospaced">
<pre>[configf:settings trim-trailing-spaces yes]</pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_job_submission_control">Job Submission Control</h3>
<div class="sect3">
<h4 id="_submit_jobs_to_host_types_based_on_test_name_2">Submit jobs to Host Types based on Test Name</h4>
<div class="sect3">
<h4 id="_job_submission_control">Job Submission Control</h4>
<div class="sect4">
<h5 id="_submit_jobs_to_host_types_based_on_test_name_2">Submit jobs to Host Types based on Test Name</h5>
<div class="listingblock">
<div class="title">In megatest.config</div>
<div class="content monospaced">
<pre>[host-types]
general   nbfake
remote    bsub

[launchers]
runfirst/sum% remote
% general

[jobtools]
launcher bsub
# if defined and not "no" flexi-launcher will bypass launcher unless
# there is no host-type match.
flexi-launcher yes</pre>
</div></div>
</div>
<div class="sect3">
<h4 id="_host_types">host-types</h4>
<div class="sect4">
<h5 id="_host_types">host-types</h5>
<div class="paragraph"><p>List of host types and the commandline to run a job on that host type.</p></div>
<div class="listingblock">
<div class="title">host-type &#8658; launch command</div>
<div class="content monospaced">
<pre>general nbfake</pre>
</div></div>
</div>
<div class="sect3">
<h4 id="_launchers">launchers</h4>
<div class="sect4">
<h5 id="_launchers">launchers</h5>
<div class="listingblock">
<div class="title">test/itempath &#8658; host-type</div>
<div class="content monospaced">
<pre>runfirst/sum% remote</pre>
</div></div>
</div>
</div>
<div class="sect2">
<h3 id="_miscellaneous_setup_items">Miscellaneous Setup Items</h3>
<div class="sect4">
<h5 id="_miscellaneous_setup_items">Miscellaneous Setup Items</h5>
<div class="paragraph"><p>Attempt to rerun tests in "STUCK/DEAD", "n/a", "ZERO_ITEMS" states.</p></div>
<div class="listingblock">
<div class="title">In megatest.config</div>
<div class="content monospaced">
<pre>[setup]
reruns 5</pre>
</div></div>
</div>
<div class="sect3">
<h4 id="_run_time_limit">Run time limit</h4>
<div class="sect4">
<h5 id="_run_time_limit">Run time limit</h5>
<div class="listingblock">
<div class="content monospaced">
<pre>[setup]
# this will automatically kill the test if it runs for more than 1h 2m and 3s
runtimelim 1h 2m 3s</pre>
</div></div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_tests_browser_view">Tests browser view</h4>
<div class="sect2">
<h3 id="_tests_browser_view">Tests browser view</h3>
<div class="paragraph"><p>The tests browser (see the Run Control tab on the dashboard) has two views for displaying the tests.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Dot (graphviz) based tree
</p>
</li>

well in that mode then use "nodot" to turn it off.</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>[setup]
nodot</pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_dashboard_settings">Dashboard settings</h3>
<div class="listingblock">
<div class="title">Runs tab buttons, font and size</div>
<div class="content monospaced">
<pre>[dashboard]
btn-height x14
btn-fontsz 10
cell-width 60</pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_database_settings">Database settings</h3>
<table class="tableblock frame-topbot grid-all"
style="
width:70%;
">
<caption class="title">Table 1. Database config settings in [setup] section of megatest.config</caption>
<caption class="title">Table 2. Database config settings in [setup] section of megatest.config</caption>
<col style="width:14%;">
<col style="width:28%;">
<col style="width:28%;">
<col style="width:28%;">
<thead>
<tr>
<th class="tableblock halign-center valign-top" >Var                       </th>

<div class="content monospaced">
<pre>[triggers]
COMPLETED/ xterm -e bash -s --</pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/usr/images/icons/note.png" alt="Note">
<img src="/nfs/pdx/disks/ice.disk.002/icfadm/pkgs/asciidoc/8.6.7/images/icons/note.png" alt="Note">
</td>
<td class="content">There is a trailing space after the --</td>
</tr></table>
</div>
</div>
<div class="sect2">
<h3 id="_override_the_toplevel_html_file">Override the Toplevel HTML File</h3>

<h2 id="_programming_api">Programming API</h2>
<div class="sectionbody">
<div class="paragraph"><p>These routines can be called from the megatest repl.</p></div>
<table class="tableblock frame-topbot grid-all"
style="
width:70%;
">
<caption class="title">Table 2. API Keys Related Calls</caption>
<caption class="title">Table 3. API Keys Related Calls</caption>
<col style="width:14%;">
<col style="width:28%;">
<col style="width:28%;">
<col style="width:28%;">
<thead>
<tr>
<th class="tableblock halign-center valign-top" >API Call                        </th>

<td class="tableblock halign-center valign-top" ><p class="tableblock">(rmt:get-keys run-id)</p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock monospaced"></p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock monospaced">( key1 key2 &#8230; )</p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock monospaced"></p></td>
</tr>
</tbody>
</table>
<div class="sect2">
<h3 id="_megatest_internals">Megatest Internals</h3>
<div class="imageblock graphviz">
<div class="content">
<img src="server.png" alt="server.png">
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_example_appendix">Appendix A: Example Appendix</h2>
<h2 id="_megatest_internals">Megatest Internals</h2>
<div class="sectionbody">
<div class="paragraph"><p>One or more optional appendixes go here at section level zero.</p></div>
<div class="sect2">
<div class="imageblock graphviz">
<h3 id="_appendix_sub_section">Appendix Sub-section</h3>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/usr/images/icons/note.png" alt="Note">
</td>
<td class="content">Preface and appendix subsections start out of sequence at level
2 (level 1 is skipped).  This only applies to multi-part book
documents.</td>
</tr></table>
</div>
</div>
</div>
</div>
<div class="sect1">
<div class="content">
<h2 id="_example_bibliography">Example Bibliography</h2>
<div class="sectionbody">
<div class="paragraph"><p>The bibliography list is a style of AsciiDoc bulleted list.</p></div>
<div class="ulist bibliography"><ul>
<li>
<p>
<a id="taoup"></a>[taoup] Eric Steven Raymond. <em>The Art of Unix
  Programming</em>. Addison-Wesley. ISBN 0-13-142901-9.
</p>
</li>
<li>
<p>
<a id="walsh-muellner"></a>[walsh-muellner] Norman Walsh &amp; Leonard Muellner.
  <em>DocBook - The Definitive Guide</em>. O&#8217;Reilly &amp; Associates. 1999.
  ISBN 1-56592-580-7.
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<img src="server.png" alt="server.png">
<h2 id="_example_glossary">Example Glossary</h2>
<div class="sectionbody">
<div class="paragraph"><p>Glossaries are optional. Glossaries entries are an example of a style
of AsciiDoc labeled lists.</p></div>
<div class="dlist glossary"><dl>
<dt>
A glossary term
</dt>
<dd>
<p>
  The corresponding (indented) definition.
</p>
</dd>
<dt>
A second glossary term
</dt>
<dd>
<p>
  The corresponding (indented) definition.
</p>
</dd>
</dl></div>
</div>
</div>
<div class="sect1">
<h2 id="_example_colophon">Example Colophon</h2>
<div class="sectionbody">
<div class="paragraph"><p>Text at the end of a book describing facts about its production.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_example_index">Example Index</h2>
<div class="sectionbody">
</div>
</div>
</div>
<div id="footnotes"><hr></div>
<div id="footer">
<div id="footer-text">
Version 1.0<br>
Last updated
Last updated 2016-10-19 10:23:07 PDT
 2016-10-14 22:36:54 MST
</div>
</div>
</body>
</html>

The Megatest Users Manual
=========================
Matt Welland <matt@kiatoa.com>
v1.0, April 2012
:doctype: book


[preface]
Preface
-------
=======

This book is organised as three sub-books; getting started, writing tests and reference.

Why Megatest?
~~~~~~~~~~~~~
-------------

The Megatest project was started for two reasons, the first was an
immediate and pressing need for a generalized tool to manage a suite
of regression tests and the second was the fact that the author had
written or maintained several such tools at different companies over
the years and it seemed a good thing to have a single open source
tool, flexible enough to meet the needs of any team doing continuous
integrating and or running a complex suite of tests for release
qualification.

Megatest Design Philosophy
~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------

Megatest is intended to provide the minimum needed resources to make
writing a suite of tests and tasks for implementing continuous build
for software, design engineering or process control (via owlfs for
example) without being specialized for any specific problem
space. Megatest in of itself does not know what constitutes a PASS or
FAIL of a test or task. In most cases megatest is best used in

 * Encapsulated - the tests run in self-contained directories and all inputs
   and outputs to the process can be found in the run areas.

 * Deployable - anyone on the team, at any site, at any time can run the flow

Megatest Architecture
~~~~~~~~~~~~~~~~~~~~~
---------------------

All data to specify the tests and configure the system is stored in
plain text files. All system state is stored in an sqlite3
database. Tests are launched using the launching system available for
the distributed compute platform in use. A template script is provided
which can launch jobs on local and remote Linux hosts. Currently
megatest uses the network filesystem to call home to your master
sqlite3 database.

include::../plan.txt[]
// to allow the getting_started.txt to be a stand-alone document use level
shifting, note that the preceding blank line is needed.
// :leveloffset: 2

include::installation.txt[]

include::getting_started.txt[]

:leveloffset: 0

include::writing_tests.txt[]
include::howto.txt[]
include::reference.txt[]

Megatest Internals
~~~~~~~~~~~~~~~~~~
------------------

["graphviz", "server.png"]
----------------------------------------------------------------------
include::server.dot[]
----------------------------------------------------------------------


[appendix]
Example Appendix
================
One or more optional appendixes go here at section level zero.

Appendix Sub-section
~~~~~~~~~~~~~~~~~~~
NOTE: Preface and appendix subsections start out of sequence at level
2 (level 1 is skipped).  This only applies to multi-part book
documents.



[bibliography]
Example Bibliography
====================
The bibliography list is a style of AsciiDoc bulleted list.

[bibliography]
- [[[taoup]]] Eric Steven Raymond. 'The Art of Unix
  Programming'. Addison-Wesley. ISBN 0-13-142901-9.
- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
  'DocBook - The Definitive Guide'. O'Reilly & Associates. 1999.
  ISBN 1-56592-580-7.


[glossary]
Example Glossary
================
Glossaries are optional. Glossaries entries are an example of a style
of AsciiDoc labeled lists.

[glossary]
A glossary term::
  The corresponding (indented) definition.

A second glossary term::
  The corresponding (indented) definition.


[colophon]
Example Colophon
================
Text at the end of a book describing facts about its production.
// [appendix]
// Example Appendix
// ================
// One or more optional appendixes go here at section level zero.
// 
// Appendix Sub-section
// ~~~~~~~~~~~~~~~~~~~
// NOTE: Preface and appendix subsections start out of sequence at level
// 2 (level 1 is skipped).  This only applies to multi-part book
// documents.
// 
// 
// 
// [bibliography]
// Example Bibliography
// ====================
// The bibliography list is a style of AsciiDoc bulleted list.
// 
// [bibliography]
// - [[[taoup]]] Eric Steven Raymond. 'The Art of Unix
//   Programming'. Addison-Wesley. ISBN 0-13-142901-9.
// - [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
//   'DocBook - The Definitive Guide'. O'Reilly & Associates. 1999.
//   ISBN 1-56592-580-7.
// 
// 
// [glossary]
// Example Glossary
// ================
// Glossaries are optional. Glossaries entries are an example of a style
// of AsciiDoc labeled lists.
// 
// [glossary]
// A glossary term::
//   The corresponding (indented) definition.
// 
// A second glossary term::
//   The corresponding (indented) definition.
// 
// 
// [colophon]
// Example Colophon
// ================
// Text at the end of a book describing facts about its production.


[index]
Example Index
=============
-------------
////////////////////////////////////////////////////////////////
The index is normally left completely empty, it's contents are
generated automatically by the DocBook toolchain.
////////////////////////////////////////////////////////////////

Reference
=========
---------

Megatest Config File Settings
-----------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Disk Space Checks
~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^

Some parameters you can put in the [setup] section of megatest.config:

-------------------
# minimum space required in a run disk 
minspace 10000000

# minimum space required in dbdir:
dbdir-space-required 100000

# script that takes path as parameter and returns number of bytes available:
free-space-script check-space.sh
-------------------

Trim trailing spaces
~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^

------------------
[configf:settings trim-trailing-spaces yes]
------------------

Job Submission Control
~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^

Submit jobs to Host Types based on Test Name
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++++++++++++++++++++++++

.In megatest.config
------------------------
[host-types]
general   nbfake
remote    bsub

[launchers]
runfirst/sum% remote
% general

[jobtools]
launcher bsub
# if defined and not "no" flexi-launcher will bypass launcher unless 
# there is no host-type match.
flexi-launcher yes
------------------------

host-types
^^^^^^^^^^
++++++++++

List of host types and the commandline to run a job on that host type.

.host-type => launch command
------------
general nbfake
------------

launchers
+++++++++
^^^^^^^^^

.test/itempath => host-type
------------
runfirst/sum% remote
------------

Miscellaneous Setup Items
~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++

Attempt to rerun tests in "STUCK/DEAD", "n/a", "ZERO_ITEMS" states.

.In megatest.config
------------------
[setup]
reruns 5
------------------

Run time limit
^^^^^^^^^^^^^^
++++++++++++++

-----------------
[setup]
# this will automatically kill the test if it runs for more than 1h 2m and 3s
runtimelim 1h 2m 3s
-----------------

Tests browser view
^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~

The tests browser (see the Run Control tab on the dashboard) has two views for displaying the tests. 

. Dot (graphviz) based tree
. No dot, plain listing

The default is the graphviz based tree but if your tests don't view
well in that mode then use "nodot" to turn it off.

-----------------
[setup]
nodot
-----------------

Dashboard settings
~~~~~~~~~~~~~~~~~~

.Runs tab buttons, font and size
------------------
[dashboard]
btn-height x14
btn-fontsz 10
cell-width 60
------------------

Database settings
~~~~~~~~~~~~~~~~~

.Database config settings in [setup] section of megatest.config
[width="70%",cols="^,2m,2m,2m",frame="topbot",options="header"]
|======================

Writing Tests
-------------
// =============

Creating a new Test
~~~~~~~~~~~~~~~~~~~

//-------------------

The following steps will add a test "yourtestname" to your testsuite. This assumes
starting from a directory where you already have a megatest.config and
runconfigs.config.

. Create a directory tests/yourtestname
. Create a file tests/yourtestname/testconfig

Road Map
--------
========

Note 1: This road-map is still evolving and subject to change without notice.

Architecture Refactor
~~~~~~~~~~~~~~~~~~~~~
Note 1: This road-map is tentative and subject to change without notice.

Goals
^^^^^

. Reduce load on the file system. Sqlite3 files on network filesystem can be
  a burden.
. Reduce number of servers and frequency of start/stop. This is mostly an
  issue of clutter but also a reduction in "moving parts".
. Coalesce activities to a single home host where possible. Give the user
  feedback that they have started the dashboard on a host other than the
  home host.
. Reduce number of processes involved in managing running tests.
Note 2: Starting over. Old plan is commented out.

Changes Needed
^^^^^^^^^^^^^^

. ACID compliant db will be on /tmp and synced to megatest.db with a five
  second max delay.
. Read/writes to db for processes on homehost will go direct to /tmp
  megatest.db file.
. Read/wites fron non-homehost processes will go through one server. Bulk
  reads (e.g. for dashboard or list-runs) will be cached on the current host
  in /tmp and synced from the home megatest.db in the testsuite area.
. Db syncs rely on the target db file timestame minus some margin.
. Since bulk reads do not use the server we can switch to simple RPC for the
  network transport.
. Test running manager process extended to manage multiple running tests.

Current Items
-------------
~~~~~~~~~~~~~

ww05 - migrate to inmem-db
~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^

. Switch to inmem db with fast sync to on disk db's [DONE]
. Server polls tasks table for next action
.. Task table used for tracking runner process [DONE]
.. Task table used for jobs to run
.. Task table used for queueing runner actions (remove runs, cleanRunExecute, etc)

[fields]
CFG_TYPE This is the refdb to use.
RUN_TYPE Can be: full or quick

[setup]
# Adjust max_concurrent_jobs to limit parallel jobs
max_concurrent_jobs 50

# This is your link path, best to set it and then not change it
linktree #{getenv PWD}/linktree
linktree #{getenv MT_RUN_AREA_HOME}/linktree

# Job tools control how your jobs are launched
[jobtools]
launcher nbfake

# As you run more tests you may need to add additional disks 
# the names are arbitrary but must be unique
[disks]
disk0 #{getenv PWD}/runs
disk0 #{getenv MT_RUN_AREA_HOME}/runs

[include local.megatest.config]

(declare (unit genexample))
(use posix regex)

(define genexample:example-logpro
#<<EOF
  ;; You should have at least one expect:required. This ensures that your process ran
  ;; comment out the line below and replace "put pattern here" with a pattern that will
  ;; always be seen in your log file if the step runs successfully.
  ;;
  (expect:required in "LogFileBody" > 0 "Put description here" #/put pattern here/)
  ;; (expect:required in "LogFileBody" > 0 "Put description here" #/put pattern here/)
  ;;
  ;; You may need ignores to suppress false error or warning hits from the later expects
  ;; NOTE: Order is important here!
  (expect:ignore   in "LogFileBody"  < 99 "Ignore the word error in comments" #/^\/\/.*error/)
  (expect:warning  in "LogFileBody"  = 0 "Any warning" #/warn/)
  (expect:error    in "LogFileBody"  = 0 "Any error"  (list #/ERROR/ #/error/)) ;; but disallow any other errors
EOF

;; Always use two or four digit decimal
;; 1.01, 1.02...1.10,1.11,1.1101 ... 1.99,2.00..

(declare (unit megatest-version))

(define megatest-version 1.6204)
(define megatest-version 1.6205)

		  ((and skip-check
			(configf:lookup test-conf "skip" "rundelay"))
		   ;; run-ids = #f means *all* runs
		   (let* ((numseconds      (common:hms-string->seconds (configf:lookup test-conf "skip" "rundelay")))
			  (running-tests   (rmt:get-tests-for-runs-mindata #f full-test-name '("RUNNING" "REMOTEHOSTSTART" "LAUNCHED") '() #f))
			  (completed-tests (rmt:get-tests-for-runs-mindata #f full-test-name '("COMPLETED" "INCOMPLETE") '("PASS" "FAIL" "ABORT") #f)) ;; ironically INCOMPLETE is same as COMPLETED in this contex
			  (last-run-times  (map db:mintest-get-event_time completed-tests))
			  (time-since-last (- (current-seconds) (if (null? last-run-times) 0 (apply max last-run-times)))))
			  (time-since-last (- (current-seconds) (if (null? last-run-times) 0 (common:max last-run-times)))))
		     (if (or (not (null? running-tests)) ;; have to skip if test is running
			     (> numseconds time-since-last))
			 (set! skip-test (conc "Skipping due to previous test run less than " (configf:lookup test-conf "skip" "rundelay") " ago"))))))
		 
		 (if skip-test
		     (begin
		       (mt:test-set-state-status-by-id run-id test-id "COMPLETED" "SKIP" skip-test)

#!/bin/bash

if ! type screen &> /dev/null;then
  xterm -geometry 180x20 -e "$*;echo Press any key to continue;bash -c 'read -n 1 -s'" &
  exit
fi

if [[ $(screen -list | egrep 'Attached|Detached'|awk '{print $1}') == "" ]];then
    # echo "No screen found for displaying to. Run \"screen\" in an xterm"
    # exit 1
    xterm -e screen &
    xterm -e screen -e^ff &
    sleep 1
    screen -X hardstatus off
    screen -X hardstatus alwayslastline
    screen -X hardstatus string '%{= kG}[ %{G}%H %{g}][%= %{= kw}%?%-Lw%?%{r}(%{W}%n*%f%t%?(%u)%?%{r})%{w}%?%+Lw%?%?%= %{g}][%{B} %m-%d %{W} %c %{g}]'
fi

cmd="cd $PWD;$*"
screen -X screen bash -c "$cmd;echo \"Press any key to continue, ctrl-a <space> to see other windows\";bash -c 'read -n 1 -s'"
screen -X screen bash -c "$cmd;echo \"Press any key to continue, ctrl-f <space> to see other windows\";bash -c 'read -n 1 -s'"