Index: docs/megatest.lyx ================================================================== --- docs/megatest.lyx +++ docs/megatest.lyx @@ -1,39 +1,138 @@ #LyX 2.0 created this file. For more info see http://www.lyx.org/ \lyxformat 413 \begin_document \begin_header -\textclass docbook-book +\textclass article +\begin_preamble +% Include the proper LaTeX packages: +%---------------------------------------------------------------------------------------------------- +\usepackage{graphicx} +\usepackage{titling} +\usepackage{ifthen} +\usepackage[absolute]{textpos} +\usepackage[colorlinks=true, + pagecolor=black, + menucolor=black, + linkcolor=black, + citecolor=blue, + pagebordercolor=1 1 1, + urlcolor=red, + plainpages=false, + pdfpagelabels=true, + bookmarksnumbered=true]{hyperref} +\usepackage{lastpage} + +\newcommand{\reportTopic}{} +\newcommand{\revisionNumber}{} +\newcommand{\documentNumber}{} + + +% Setup the right-hand header to display the current doc section: +%---------------------------------------------------------------------------------------------------- +\renewcommand{\sectionmark}[1]{\markright{#1}} +\renewcommand{\subsectionmark}[1]{\markright{#1}} + +% Setup for roman numeral page numbers until TOC: +%---------------------------------------------------------------------------------------------------- +\newboolean{romanpn} + +\pagenumbering{roman} +\setboolean{romanpn}{true} +\let\myTOC\tableofcontents + +\renewcommand\tableofcontents{% +\myTOC +\clearpage +\pagenumbering{arabic} +\setboolean{romanpn}{false} +} + +% Modify titlepage format: +%---------------------------------------------------------------------------------------------------- +\setlength{\TPHorizModule}{1in} +\setlength{\TPVertModule}{\TPHorizModule} +\textblockorigin{3.25in}{1in} + +\pretitle + { + \begin{flushright}\LARGE\sffamily + \thispagestyle{empty} + \begin{textblock}{4}(0,0) + \includegraphics[width=2in,keepaspectratio=true] +{/home/matt/data/megatest/docs/megatest_logo.png} + \end{textblock} + \vspace{1in} + } + +\posttitle{\par\end{flushright}} + +\preauthor{\begin{flushright} \large \sffamily \lineskip 0.5em +\begin{tabular}[t]{c}} +\postauthor{\end{tabular} \par\end{flushright}} + +\predate{\begin{flushright}\large \sffamily Document Number: \documentNumber \\ Revision Number: \revisionNumber \\} + +\postdate{ +\vspace{2in} +\\Matt Welland. +\par\end{flushright}} + +% Setup "fancy" page layout: +%---------------------------------------------------------------------------------------------------- +\fancyhf{} +\setlength{\topmargin}{-1in} +\setlength{\headheight}{1in} +\setlength{\headsep}{0.5in} +\setlength{\oddsidemargin}{0.25in} +\setlength{\evensidemargin}{\oddsidemargin} +\setlength{\textwidth}{6in} +\setlength{\headwidth}{\textwidth} +\setlength{\textheight}{8.375in} +\setlength{\footskip}{0.5in} + +% Setup header: +%------------------------------------------------------------------------------------------ +\fancyhead[L]{\sffamily \bfseries \large Megatest.\\\mdseries \reportTopic} +\fancyhead[R]{\sffamily \bfseries \large User Manual\\ \mdseries \nouppercase{\rightmark}} + +% Setup footer: +%------------------------------------------------------------------------------------------ +\renewcommand{\footrulewidth}{0.4pt} +\fancyfoot[L]{\sffamily \bfseries \documentNumber \\ \mdseries Revision: \revisionNumber} +\fancyfoot[C]{\sffamily \bfseries\thedate \\ \mdseries Free Software. License: GPL v2.0} +\fancyfoot[R]{\ifthenelse{\boolean{romanpn}}{\sffamily \thepage}{\sffamily \bfseries Page \thepage\ of \pageref{LastPage}}} +\end_preamble \use_default_options false \maintain_unincluded_children false \language english \language_package default \inputencoding auto \fontencoding global -\font_roman default -\font_sans default -\font_typewriter default +\font_roman times +\font_sans helvet +\font_typewriter courier \font_default_family default \use_non_tex_fonts false \font_sc false \font_osf false \font_sf_scale 100 \font_tt_scale 100 \graphics default \default_output_format default -\output_sync 1 +\output_sync 0 \bibtex_command default \index_command default -\paperfontsize default +\paperfontsize 11 \spacing single \use_hyperref false -\papersize default +\papersize letterpaper \use_geometry false -\use_amsmath 0 +\use_amsmath 1 \use_esint 0 -\use_mhchem 1 +\use_mhchem 0 \use_mathdots 1 \cite_engine basic \use_bibtopic false \use_indices false \paperorientation portrait @@ -43,57 +142,334 @@ \shortcut idx \color #008000 \end_index \secnumdepth 3 \tocdepth 3 -\paragraph_separation indent -\paragraph_indentation default +\paragraph_separation skip +\defskip medskip \quotes_language english \papercolumns 1 \papersides 1 -\paperpagestyle default +\paperpagestyle fancy \tracking_changes false \output_changes false \html_math_output 0 \html_css_as_file 0 \html_be_strict false \end_header \begin_body + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +renewcommand{ +\backslash +documentNumber}{TSETAGEM-011} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +renewcommand{ +\backslash +reportTopic}{Megatest User Manual} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +renewcommand{ +\backslash +revisionNumber}{v1.25} +\end_layout + +\end_inset + + +\end_layout \begin_layout Title -Megatest +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +reportTopic \end_layout -\begin_layout Date -5/5/2011 +\end_inset + + \end_layout \begin_layout Author -Matt Welland +Matthew Welland \end_layout -\begin_layout Abstract -Megatest is a minimalistic tool to help automate and manage the running - of a suite of regression tests or other processes and to roll up the results - for display on a web page or dashboard. +\begin_layout Date +Sept. + 20, +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +thispagestyle{empty} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset Newpage newpage +\end_inset + + +\begin_inset ERT +status collapsed + +\begin_layout Plain Layout + + +\backslash +copyright +\end_layout + +\end_inset + +2011 Matthew Welland. + All rights reserved. + +\end_layout + +\begin_layout Standard +Megatest is free software released under the General Public License v2.0. + Please see the file COPYING in the source distribution for details. + +\end_layout + +\begin_layout Standard +\begin_inset VSpace medskip +\end_inset + +Email: matt@kiatoa.com. + +\end_layout + +\begin_layout Standard +Web: www.kiatoa.com/fossils/megatest +\end_layout + +\begin_layout Standard +\begin_inset VSpace medskip +\end_inset + +This document is believed to be acurate at the time of writing but as with + any opensource project the source code itself is the final arbiter of the + softwares behaviour. + It is the responsibility of the end user to validate that the code will + perform as they expect. + The author assumes no responsibility for any inaccuracies that this document + may contain. + In no event will Matthew Welland be liable for direct, indirect, special, + exemplary, incidental, or consequential damages resulting from any defect + or omission in this document, even if advised of the possibility of such + damages. + +\end_layout + +\begin_layout Standard +This document is a snapshot in time and the Megatest software has likely + been changed since publication. + This document and the product that it describes may be improved at any + time, without notice or obligation. + +\end_layout + +\begin_layout Standard +\begin_inset Newpage newpage +\end_inset + + +\end_layout + +\begin_layout Section* +Document Revision History +\end_layout + +\begin_layout Standard + +\shape italic +Notable revisions of the software are occasionally documented here +\shape default +. +\end_layout + +\begin_layout Standard +\align center +\begin_inset Tabular + + + + + + + + +\begin_inset Text + +\begin_layout Plain Layout +Version +\end_layout + +\end_inset + + +\begin_inset Text + +\begin_layout Plain Layout +Author +\end_layout + +\end_inset + + +\begin_inset Text + +\begin_layout Plain Layout +Description +\end_layout + +\end_inset + + +\begin_inset Text + +\begin_layout Plain Layout +Date +\end_layout + +\end_inset + + + + +\begin_inset Text + +\begin_layout Plain Layout +0.1 +\end_layout + +\end_inset + + +\begin_inset Text + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\begin_inset Text + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\begin_inset Text + +\begin_layout Plain Layout +\begin_inset ERT +status collapsed + +\begin_layout Plain Layout + + +\backslash +thedate +\end_layout + +\end_inset + + +\end_layout + +\end_inset + + + + +\end_inset + + \end_layout \begin_layout Standard +\begin_inset Newpage newpage +\end_inset + + \begin_inset CommandInset toc LatexCommand tableofcontents \end_inset \end_layout -\begin_layout Chapter -About Megatest +\begin_layout Standard +\begin_inset Newpage newpage +\end_inset + + \end_layout \begin_layout Section +Introduction +\end_layout + +\begin_layout Subsection Megatest design philosophy \end_layout \begin_layout Standard Megatest is intended to provide the minimum needed resources to make writing @@ -105,11 +481,11 @@ tool to parse, analyze and decide on the test outcome. A call to megatest can then be made to record the result. \end_layout -\begin_layout Section +\begin_layout Subsection Megatest architecture \end_layout \begin_layout Standard All data to specify the tests and configure the system is stored in plain @@ -128,42 +504,38 @@ \end_inset to your master sqlite3 database. \end_layout -\begin_layout Chapter -Installation -\end_layout - \begin_layout Section -Compilation +Installation \end_layout \begin_layout Subsection Dependencies \end_layout \begin_layout Standard -Chicken scheme and a number of eggs are required for building megatest. +Chicken scheme and a number of +\begin_inset Quotes eld +\end_inset + +eggs +\begin_inset Quotes erd +\end_inset + + are required for building megatest. See the file utils/installall.sh for an automated way to install the dependencie s on Linux. \end_layout \begin_layout Subsection -Build and install +Build and Install \end_layout \begin_layout Standard -Run -\begin_inset Quotes eld -\end_inset - -make test -\begin_inset Quotes erd -\end_inset - - to create the megatest executable. +Run “make test” to create the megatest executable. You may wish to copy the executable to a centrally accessible location. \end_layout \begin_layout Section Setup @@ -177,11 +549,11 @@ Create the file megatest.config using the megatest.config template from the tests directory. At a minimum you need the following: \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -290,21 +662,20 @@ \end_layout \begin_layout Standard This file is used to set environment variables that are run specific. You can simply create an empty file to start. +\end_layout + +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout # runconfigs.config -\end_layout - -\begin_layout Plain Layout - \end_layout \end_inset @@ -313,14 +684,10 @@ \begin_layout Subsection Create the tests directory and your first test \end_layout \begin_layout Standard -The structure should look like this: -\end_layout - -\begin_layout Paragraph \begin_inset listings inline false status open \begin_layout Plain Layout @@ -365,11 +732,11 @@ \begin_layout Subsection Create the testconfig file for your test \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -389,11 +756,11 @@ \begin_layout Subsection Create your test running script, main.sh \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -410,14 +777,10 @@ $MT_MEGATEST -runstep mystep1 "sleep 20;echo Done" -m "mystep1 is done" \end_layout \begin_layout Plain Layout -\end_layout - -\begin_layout Plain Layout - $MT_MEGATEST -test-status :state COMPLETED :status PASS -m "This is a comment" \end_layout \end_inset @@ -426,11 +789,11 @@ \begin_layout Subsection Run megatest and watch your run progress \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -468,28 +831,19 @@ \end_inset \end_layout -\begin_layout Code - -\end_layout - -\begin_layout Chapter +\begin_layout Section How to Write Tests \end_layout -\begin_layout Section +\begin_layout Subsection A Simple Test with one Step \end_layout -\begin_layout Subsection -Create your test directory. - The directory name will be the name of the test -\end_layout - -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -506,17 +860,14 @@ \end_layout \begin_layout Subsection -Create your testconfig file. - This file contains various specifications for your test. - For our example the test author has chosen to write the test using csh - scripting. +Create your testconfig file \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -542,21 +893,22 @@ \end_layout \begin_layout Subsection -Create your main.csh script +Create the main.csh script \end_layout \begin_layout Standard Note: Using csh is NOT recommended. Use bash, perl, ruby, zsh or anything other than csh. - We use csh here because it is popular in some industries. + We use csh here because it is popular in the EDA industry for which Megatest + was originally created. \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -607,67 +959,27 @@ \end_layout \begin_layout Standard You can now run megatest and the created test directory will contain the - new files -\begin_inset Quotes eld -\end_inset - -run_simulation.html -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -run_simulation.log -\begin_inset Quotes erd -\end_inset - -. + new files “run_simulation.html” and “run_simulation.log”. If you are using the dashboard you can click on the run and then push the - -\begin_inset Quotes eld -\end_inset - -View log -\begin_inset Quotes erd -\end_inset - - button to view the log file in firefox. + “View log” button to view the log file in firefox. \end_layout -\begin_layout Section +\begin_layout Subsection Simple Test with Multiple Steps \end_layout \begin_layout Standard To run multiple steps simply add them to the main.csh file. - Here we add a step to test -\begin_inset Quotes eld -\end_inset - -cpu2 -\begin_inset Quotes erd -\end_inset - -. + Here we add a step to test “cpu2”. The second step that tests cpu2 will only run after the step that tested - -\begin_inset Quotes eld -\end_inset - -cpu1 -\begin_inset Quotes erd -\end_inset - - completes. + “cpu1” completes. \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -725,11 +1037,11 @@ \end_layout \begin_layout Section -Simple Test with Multiple Steps, Some in Parallel +Simple Test with Multiple Steps, Some in Parallel \end_layout \begin_layout Subsection The Makefile \end_layout @@ -736,39 +1048,15 @@ \begin_layout Standard A good way to run steps in parallel within a single test, especially when there are following steps, is to use the Unix Make utility. Writing Makefiles is beyond the scope of this document but here is a minimal - example that will run -\begin_inset Quotes eld -\end_inset - -runsim cpu1 -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -runsim cpu2 -\begin_inset Quotes erd -\end_inset - - in parallel. - For more information on make try -\begin_inset Quotes eld -\end_inset - -info make -\begin_inset Quotes erd -\end_inset - - at the Linux command prompt. + example that will run “runsim cpu1” and “runsim cpu2” in parallel. + For more information on make try “info make” at the Linux command prompt. \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -842,10 +1130,12 @@ \begin_layout Plain Layout \end_layout \begin_layout Plain Layout +\noindent +\align left make -j 2 \end_layout \begin_layout Plain Layout @@ -869,11 +1159,11 @@ \begin_layout Subsection Update your testconfig file for iteration \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout @@ -885,10 +1175,12 @@ runscript main.csh \end_layout \begin_layout Plain Layout +\noindent +\align left \end_layout \begin_layout Plain Layout @@ -907,274 +1199,245 @@ \begin_layout Subsection Rewrite your main.csh for iteration \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout +\noindent +\align left #!/bin/tcsh -x \end_layout \begin_layout Plain Layout +\noindent +\align left \end_layout \begin_layout Plain Layout +\noindent +\align left # run the cpu simulation but now use the environment variable $CPU \end_layout \begin_layout Plain Layout +\noindent +\align left # to select what cpu to run the simulation against \end_layout \begin_layout Plain Layout +\noindent +\align left \end_layout \begin_layout Plain Layout +\noindent +\align left $MT_MEGATEST -runstep run_simulation -logpro runsim.logpro "runsim $CPU" \end_layout \begin_layout Plain Layout +\noindent +\align left # As of version 1.07 Megatest automatically converts a status of "0" \end_layout \begin_layout Plain Layout +\noindent +\align left # to "PASS", any other number to "FAIL" and directly uses the value of \end_layout \begin_layout Plain Layout +\noindent +\align left # a string passed in. \end_layout \begin_layout Plain Layout +\noindent +\align left $MT_MEGATEST -test-status :state COMPLETED :status $? \end_layout \end_inset \end_layout -\begin_layout Section +\begin_layout Subsection Tests with Inter-test dependencies \end_layout \begin_layout Standard Sometimes a test depends on the output from a previous test or it may not make sense to run a test is another test does not complete with status - -\begin_inset Quotes eld -\end_inset - -PASS -\begin_inset Quotes erd -\end_inset - -. - In either of these scenarios you can use the -\begin_inset Quotes eld -\end_inset - -waiton -\begin_inset Quotes erd -\end_inset - - keyword in your testconfig file to indicate that this test must wait on - one or more tests to complete before being launched. - In this example there is no point in running the -\begin_inset Quotes eld -\end_inset - -system -\begin_inset Quotes erd -\end_inset - - test if the -\begin_inset Quotes eld -\end_inset - -cpu -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -mem -\begin_inset Quotes erd -\end_inset - - tests either do not complete or complete but with status -\begin_inset Quotes eld -\end_inset - -FAIL -\begin_inset Quotes erd -\end_inset - -. + “PASS”. + In either of these scenarios you can use the “waiton” keyword in your testconfi +g file to indicate that this test must wait on one or more tests to complete + before being launched. + In this example there is no point in running the “system” test if the “cpu” + and “mem” tests either do not complete or complete but with status “FAIL”. \end_layout -\begin_layout Paragraph +\begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout +\noindent +\align left # testconfig for the "system" test \end_layout \begin_layout Plain Layout +\noindent +\align left [setup] \end_layout \begin_layout Plain Layout +\noindent +\align left runscript main.csh \end_layout \begin_layout Plain Layout +\noindent +\align left waiton cpu mem \end_layout \end_inset \end_layout -\begin_layout Chapter +\begin_layout Section Reference \end_layout -\begin_layout Section +\begin_layout Subsection Configuration file Syntax \end_layout -\begin_layout Subsection +\begin_layout Subsubsection Sections \end_layout \begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + [section name] \end_layout -\begin_layout Quotation -This creates a section named -\begin_inset Quotes eld -\end_inset - -section name -\begin_inset Quotes erd \end_inset \end_layout -\begin_layout Subsection +\begin_layout Standard +This creates a section named “section name” +\end_layout + +\begin_layout Subsubsection Variables \end_layout \begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + VARX has this value \end_layout -\begin_layout Quotation -The variable -\begin_inset Quotes eld -\end_inset - -VARX -\begin_inset Quotes erd -\end_inset - - will have the value -\begin_inset Quotes eld -\end_inset - -has this value -\begin_inset Quotes erd \end_inset \end_layout -\begin_layout Subsection +\begin_layout Standard +The variable “VARX” will have the value “has this value” +\end_layout + +\begin_layout Subsubsection Includes \end_layout \begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + [include filename] \end_layout -\begin_layout Quotation -The file named -\begin_inset Quotes eld -\end_inset - -filename -\begin_inset Quotes erd -\end_inset - - will be included as if part of the calling file. - NOTE: This means no section can be named -\begin_inset Quotes eld -\end_inset - -include -\begin_inset Quotes eld -\end_inset - - (with the whitespace). -\end_layout - -\begin_layout Subsection +\end_inset + + +\end_layout + +\begin_layout Standard +The file named “filename” will be included as if part of the calling file. + NOTE: This means no section can be named “include “ (with the whitespace). +\end_layout + +\begin_layout Subsubsection Setting a variable by running a command \end_layout \begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + VARNAME [system ls /tmp] \end_layout -\begin_layout Quotation -The variable -\begin_inset Quotes eld -\end_inset - -VARNAME -\begin_inset Quotes erd -\end_inset - - will get a value created by the Unix command -\begin_inset Quotes eld -\end_inset - -ls /tmp -\begin_inset Quotes erd -\end_inset - -. +\end_inset + + +\end_layout + +\begin_layout Standard +The variable “VARNAME” will get a value created by the Unix command “ls + /tmp”. All lines of output from the command will be joined with a space. \end_layout -\begin_layout Subsection +\begin_layout Subsubsection Notes \end_layout \begin_layout Itemize Some variables are infered as lists. @@ -1183,21 +1446,20 @@ \begin_layout Itemize Comments (lines starting with #) and blank lines are ignored. \end_layout -\begin_layout Section +\begin_layout Subsection Environment variables \end_layout \begin_layout Standard \begin_inset Tabular - - - - - + + + + \begin_inset Text \begin_layout Plain Layout @@ -1204,278 +1466,181 @@ Variable \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Purpose \end_layout -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout -Default value/Comment -\end_layout - \end_inset - + \begin_inset Text \begin_layout Plain Layout MT_CMDINFO \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Conveys test variables to the megatest test runner. \end_layout -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout -Not for use by the end user -\end_layout - \end_inset - + \begin_inset Text \begin_layout Plain Layout MT_TEST_RUN_DIR \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Directory assigned by megatest for the test to run. \end_layout -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout -Tests can consider this their -\begin_inset Quotes eld -\end_inset - -home -\begin_inset Quotes erd -\end_inset - - directory -\end_layout - \end_inset - + \begin_inset Text \begin_layout Plain Layout MT_TEST_NAME \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Name of the test, corrosponds to the directory name under tests. \end_layout -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout - -\end_layout - \end_inset - + \begin_inset Text \begin_layout Plain Layout MT_ITEM_INFO \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Iterated tests will set this to a sequence of key/values ((KEY val) ...) \end_layout -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout - -\end_layout - \end_inset - + \begin_inset Text \begin_layout Plain Layout MT_RUN_AREA_HOME \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Directory where megatest was launched from and where the tests code can be found \end_layout -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout - -\end_layout - \end_inset - + \begin_inset Text \begin_layout Plain Layout MT_RUNNAME \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Name of this run as set by the :runname parameter \end_layout -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout - -\end_layout - \end_inset - + \begin_inset Text \begin_layout Plain Layout MT_MEGATEST \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Path/Filename to megatest executable. - Found either from called path or but using the -\begin_inset Quotes eld -\end_inset - -exectuable -\begin_inset Quotes erd -\end_inset - - keyword in the [setup] section. -\end_layout - -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout - + Found either from called path or but using the “exectuable” keyword in + the [setup] section. \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout .... \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout The field values as set on the megatest -runall command line (e.g. :field1 abc) \end_layout -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout -Planning ahead your field names is important so as to avoid collisions with - other environment variables -\end_layout - \end_inset @@ -1482,27 +1647,23 @@ \end_inset \end_layout -\begin_layout Section -Configuration files -\end_layout - \begin_layout Subsection megatest.config \end_layout \begin_layout Standard \begin_inset Tabular - - - - - - + + + + + + \begin_inset Text \begin_layout Plain Layout @@ -1527,11 +1688,11 @@ value \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout required \end_layout @@ -1574,11 +1735,11 @@ if variable is not defined no limit on jobs \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout no \end_layout @@ -1621,11 +1782,11 @@ full path to megatest binary \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout no \end_layout @@ -1642,47 +1803,47 @@ \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout runsdir \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout full path to where the link tree to all runs will be created \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout no \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Because your runs may be spread out over several disk partitions a central link tree is created to make finding all the runs easy. @@ -1717,11 +1878,11 @@ string of letters, numbers and underscore \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout at least one \end_layout @@ -1737,48 +1898,48 @@ \end_inset - + \begin_inset Text \begin_layout Plain Layout [jobtools] \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout launcher \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout command line used to launch jobs - the job command (megatest -execute) will be appended to this \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout no \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -1785,47 +1946,47 @@ \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout workhosts \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout list of hostnames to run jobs on NOT SUPPORTED RIGHT NOW \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout n/a \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -1859,11 +2020,11 @@ any string \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout no \end_layout @@ -1908,11 +2069,11 @@ a valid path writable by the test launching process and by the test process \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout yes \end_layout @@ -1943,16 +2104,16 @@ \end_layout \begin_layout Standard \begin_inset Tabular - - - - - - + + + + + + \begin_inset Text \begin_layout Plain Layout @@ -1977,11 +2138,11 @@ value \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout required? \end_layout @@ -2024,11 +2185,11 @@ any \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout no \end_layout @@ -2046,47 +2207,47 @@ \end_inset - + \begin_inset Text \begin_layout Plain Layout [field1value/field2value...] \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout string of letters, numbers and underscore \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout any \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout no \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout the values in this section will be set for any run where field1 is field1value, field2 is field2value and fieldN is fieldNvalue. @@ -2228,16 +2389,16 @@ \end_layout \begin_layout Standard \begin_inset Tabular - - - - - - + + + + + + \begin_inset Text \begin_layout Plain Layout @@ -2262,11 +2423,11 @@ value \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout required? \end_layout @@ -2309,11 +2470,11 @@ name of script to execute for this test \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout yes \end_layout @@ -2330,47 +2491,47 @@ \end_inset - + \begin_inset Text \begin_layout Plain Layout [requirements] \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout waiton \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout list of valid test names \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout no \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout This test will not run until the named tests are state completed and status PASS @@ -2378,47 +2539,47 @@ \end_inset - + \begin_inset Text \begin_layout Plain Layout [items] \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout any valid \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout list of values \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout no \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout The test will be repeated once for each item with the variable name set to the value. @@ -2444,12 +2605,12 @@ \begin_inset Tabular - - + + \begin_inset Text \begin_layout Plain Layout @@ -2617,20 +2778,20 @@ stepname \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout record a step \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout requires :state and :status \end_layout @@ -2655,20 +2816,20 @@ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout record the test status \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout requires :state and :status \end_layout @@ -2693,20 +2854,20 @@ logfilename \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout set the logfile name for a test \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout path is assumed to be relative to the test run directory \end_layout @@ -2731,20 +2892,20 @@ logfilename \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout set the logfile name for the top test in an iterated test run \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout each sub test can have its own logfile set \end_layout @@ -2776,20 +2937,20 @@ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout sets a comment for the step, test or run \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -2814,20 +2975,20 @@ [a-zA-Z0-9_-]+ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout directory in which this run will be stored in the test run area \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -2852,21 +3013,21 @@ any value \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Set the step or test state, this is stored in the state field in the steps or tests table respectively \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout For tests Megatest recognises \begin_inset Quotes eld @@ -2907,21 +3068,21 @@ any value \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Set the step or test status, this is stored in the status field in the steps or tests table respectively \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout For tests Megatest recognises \begin_inset Quotes eld @@ -2970,20 +3131,20 @@ any value, % is wildcard \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Respects -itempatt and -testpatt for filters \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -3008,20 +3169,20 @@ any value, % is wildcard \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -3046,20 +3207,20 @@ any value, % is wildcard \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -3084,20 +3245,20 @@ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Print the keys being used for this database \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -3122,11 +3283,11 @@ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Test will not re-run if in the \begin_inset Quotes eld @@ -3155,11 +3316,11 @@ , using -force will force the run to be launched. \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout WARNING: The -force switch will bypass any \begin_inset Quotes eld @@ -3192,21 +3353,21 @@ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Launch an xterm instead of run the test. The xterm will have the environment that the test would see. \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -3231,11 +3392,11 @@ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Remove a run, test or subtest from the database and the disk. Cannot be undone. @@ -3242,11 +3403,11 @@ Requires -testpatt, -itempatt, :runname and all keys be specified. \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -3273,20 +3434,20 @@ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -3311,21 +3472,21 @@ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout Used inside a test to run a step, record the start and end of the step and optionally analyze the output using logpro. \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -3350,21 +3511,21 @@ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout If using logpro to asses the PASS/FAIL status of the step you specify the logpro file with this parameter. \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout \end_layout @@ -3376,8 +3537,17 @@ \end_inset \end_layout + +\begin_layout Section +\start_of_appendix +Data +\end_layout + +\begin_layout Section +References +\end_layout \end_body \end_document DELETED docs/megatest_new.lyx Index: docs/megatest_new.lyx ================================================================== --- docs/megatest_new.lyx +++ /dev/null @@ -1,1325 +0,0 @@ -#LyX 2.0 created this file. For more info see http://www.lyx.org/ -\lyxformat 413 -\begin_document -\begin_header -\textclass article -\begin_preamble -% Include the proper LaTeX packages: -%---------------------------------------------------------------------------------------------------- -\usepackage{graphicx} -\usepackage{titling} -\usepackage{ifthen} -\usepackage[absolute]{textpos} -\usepackage[colorlinks=true, - pagecolor=black, - menucolor=black, - linkcolor=black, - citecolor=blue, - pagebordercolor=1 1 1, - urlcolor=red, - plainpages=false, - pdfpagelabels=true, - bookmarksnumbered=true]{hyperref} -\usepackage{lastpage} - -\newcommand{\reportTopic}{} -\newcommand{\revisionNumber}{} -\newcommand{\documentNumber}{} - - -% Setup the right-hand header to display the current doc section: -%---------------------------------------------------------------------------------------------------- -\renewcommand{\sectionmark}[1]{\markright{#1}} -\renewcommand{\subsectionmark}[1]{\markright{#1}} - -% Setup for roman numeral page numbers until TOC: -%---------------------------------------------------------------------------------------------------- -\newboolean{romanpn} - -\pagenumbering{roman} -\setboolean{romanpn}{true} -\let\myTOC\tableofcontents - -\renewcommand\tableofcontents{% -\myTOC -\clearpage -\pagenumbering{arabic} -\setboolean{romanpn}{false} -} - -% Modify titlepage format: -%---------------------------------------------------------------------------------------------------- -\setlength{\TPHorizModule}{1in} -\setlength{\TPVertModule}{\TPHorizModule} -\textblockorigin{3.25in}{1in} - -\pretitle - { - \begin{flushright}\LARGE\sffamily - \thispagestyle{empty} - \begin{textblock}{4}(0,0) - \includegraphics[width=2in,keepaspectratio=true] -{/home/matt/data/megatest/docs/megatest_logo.png} - \end{textblock} - \vspace{1in} - } - -\posttitle{\par\end{flushright}} - -\preauthor{\begin{flushright} \large \sffamily \lineskip 0.5em -\begin{tabular}[t]{c}} -\postauthor{\end{tabular} \par\end{flushright}} - -\predate{\begin{flushright}\large \sffamily Document Number: \documentNumber \\ Revision Number: \revisionNumber \\} - -\postdate{ -\vspace{2in} -\\Matt Welland. -\par\end{flushright}} - -% Setup "fancy" page layout: -%---------------------------------------------------------------------------------------------------- -\fancyhf{} -\setlength{\topmargin}{-1in} -\setlength{\headheight}{1in} -\setlength{\headsep}{0.5in} -\setlength{\oddsidemargin}{0.25in} -\setlength{\evensidemargin}{\oddsidemargin} -\setlength{\textwidth}{6in} -\setlength{\headwidth}{\textwidth} -\setlength{\textheight}{8.375in} -\setlength{\footskip}{0.5in} - -% Setup header: -%------------------------------------------------------------------------------------------ -\fancyhead[L]{\sffamily \bfseries \large Megatest.\\\mdseries \reportTopic} -\fancyhead[R]{\sffamily \bfseries \large User Manual\\ \mdseries \nouppercase{\rightmark}} - -% Setup footer: -%------------------------------------------------------------------------------------------ -\renewcommand{\footrulewidth}{0.4pt} -\fancyfoot[L]{\sffamily \bfseries \documentNumber \\ \mdseries Revision: \revisionNumber} -\fancyfoot[C]{\sffamily \bfseries\thedate \\ \mdseries Use at your own risk} -\fancyfoot[R]{\ifthenelse{\boolean{romanpn}}{\sffamily \thepage}{\sffamily \bfseries Page \thepage\ of \pageref{LastPage}}} -\end_preamble -\use_default_options false -\maintain_unincluded_children false -\language english -\language_package default -\inputencoding auto -\fontencoding global -\font_roman times -\font_sans helvet -\font_typewriter courier -\font_default_family default -\use_non_tex_fonts false -\font_sc false -\font_osf false -\font_sf_scale 100 -\font_tt_scale 100 - -\graphics default -\default_output_format default -\output_sync 0 -\bibtex_command default -\index_command default -\paperfontsize 11 -\spacing single -\use_hyperref false -\papersize letterpaper -\use_geometry false -\use_amsmath 1 -\use_esint 0 -\use_mhchem 0 -\use_mathdots 1 -\cite_engine basic -\use_bibtopic false -\use_indices false -\paperorientation portrait -\suppress_date false -\use_refstyle 0 -\index Index -\shortcut idx -\color #008000 -\end_index -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation skip -\defskip medskip -\quotes_language english -\papercolumns 1 -\papersides 1 -\paperpagestyle fancy -\tracking_changes false -\output_changes false -\html_math_output 0 -\html_css_as_file 0 -\html_be_strict false -\end_header - -\begin_body - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Plain Layout - - -\backslash -renewcommand{ -\backslash -documentNumber}{TSETAGEM-011} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Plain Layout - - -\backslash -renewcommand{ -\backslash -reportTopic}{Megatest User Manual} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Plain Layout - - -\backslash -renewcommand{ -\backslash -revisionNumber}{v1.25} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Title -\begin_inset ERT -status collapsed - -\begin_layout Plain Layout - - -\backslash - -\backslash - -\backslash -reportTopic -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Author -Matthew Welland -\end_layout - -\begin_layout Date -Sept. - 20, 2011 -\end_layout - -\begin_layout Standard -\begin_inset ERT -status collapsed - -\begin_layout Plain Layout - - -\backslash -thispagestyle{empty} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Newpage newpage -\end_inset - - -\begin_inset ERT -status collapsed - -\begin_layout Plain Layout - - -\backslash -copyright -\end_layout - -\end_inset - -2011 Matthew Welland. - All rights reserved. - -\end_layout - -\begin_layout Standard -Megatest is free software released under the General Public License v2.0. - Please see the file COPYING in the source distribution for details. - -\end_layout - -\begin_layout Standard -\begin_inset VSpace medskip -\end_inset - -Email: matt@kiatoa.com. - -\end_layout - -\begin_layout Standard -Web: www.kiatoa.com/fossils/megatest -\end_layout - -\begin_layout Standard -\begin_inset VSpace medskip -\end_inset - -This document is believed to be acurate at the time of writing but as with - any opensource project the source code itself is the final arbiter of the - softwares behaviour. - It is the responsibility of the end user to validate that the code will - perform as they expect. - The author assumes no responsibility for any inaccuracies that this document - may contain. - In no event will Matthew Welland be liable for direct, indirect, special, - exemplary, incidental, or consequential damages resulting from any defect - or omission in this document, even if advised of the possibility of such - damages. - -\end_layout - -\begin_layout Standard -This document is a snapshot in time and the Megatest software has likely - been changed since publication. - This document and the product that it describes may be improved at any - time, without notice or obligation. - -\end_layout - -\begin_layout Standard -\begin_inset Newpage newpage -\end_inset - - -\end_layout - -\begin_layout Section* -Document Revision History -\end_layout - -\begin_layout Standard - -\shape italic -Notable revisions of the software are occasionally documented here -\shape default -. -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular - - - - - - - - -\begin_inset Text - -\begin_layout Plain Layout -Version -\end_layout - -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout -Author -\end_layout - -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout -Description -\end_layout - -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout -Date -\end_layout - -\end_inset - - - - -\begin_inset Text - -\begin_layout Plain Layout -0.1 -\end_layout - -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout - -\end_layout - -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout - -\end_layout - -\end_inset - - -\begin_inset Text - -\begin_layout Plain Layout -\begin_inset ERT -status collapsed - -\begin_layout Plain Layout - - -\backslash -thedate -\end_layout - -\end_inset - - -\end_layout - -\end_inset - - - - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Newpage newpage -\end_inset - - -\begin_inset CommandInset toc -LatexCommand tableofcontents - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Newpage newpage -\end_inset - - -\end_layout - -\begin_layout Section -Introduction -\end_layout - -\begin_layout Subsection -Megatest design philosophy -\end_layout - -\begin_layout Standard -Megatest is intended to provide the minimum needed resources to make writing - a suite of tests 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. - In most cases megatest is best used in conjunction with logpro or a similar - tool to parse, analyze and decide on the test outcome. - A call to megatest can then be made to record the result. - -\end_layout - -\begin_layout Subsection -Megatest architecture -\end_layout - -\begin_layout Standard -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 -\begin_inset Quotes eld -\end_inset - -call home -\begin_inset Quotes erd -\end_inset - - to your master sqlite3 database. -\end_layout - -\begin_layout Section -Installation -\end_layout - -\begin_layout Subsection -Dependencies -\end_layout - -\begin_layout Standard -Chicken scheme and a number of -\begin_inset Quotes eld -\end_inset - -eggs -\begin_inset Quotes erd -\end_inset - - are required for building megatest. - See the file utils/installall.sh for an automated way to install the dependencie -s on Linux. -\end_layout - -\begin_layout Subsection -Build and Install -\end_layout - -\begin_layout Standard -Run “make test” to create the megatest executable. - You may wish to copy the executable to a centrally accessible location. -\end_layout - -\begin_layout Section -Setup -\end_layout - -\begin_layout Subsection -Create megatest.config -\end_layout - -\begin_layout Standard -Create the file megatest.config using the megatest.config template from the - tests directory. - At a minimum you need the following: -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -# Fields are the keys under which your test runs are organized -\end_layout - -\begin_layout Plain Layout - -[fields] -\end_layout - -\begin_layout Plain Layout - -field1 TEXT -\end_layout - -\begin_layout Plain Layout - -field2 TEXT -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -[jobtools] -\end_layout - -\begin_layout Plain Layout - -# The launcher launches jobs to the local or remote hosts, -\end_layout - -\begin_layout Plain Layout - -# the job is managed on the target host by megatest, -\end_layout - -\begin_layout Plain Layout - -# comment out launcher to run local only. - An example launcher -\end_layout - -\begin_layout Plain Layout - -# "nbfake" can be found in the utils directory. - -\end_layout - -\begin_layout Plain Layout - -launcher nbfake -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -# The disks section specifies where the tests will be run. - As you -\end_layout - -\begin_layout Plain Layout - -# run out of space in a partition you can add additional disks -\end_layout - -\begin_layout Plain Layout - -# entries. -\end_layout - -\begin_layout Plain Layout - -# Format is: -\end_layout - -\begin_layout Plain Layout - -# name /path/to/area -\end_layout - -\begin_layout Plain Layout - -[disks] -\end_layout - -\begin_layout Plain Layout - -disk1 /tmp -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Create runconfigs.config -\end_layout - -\begin_layout Standard -This file is used to set environment variables that are run specific. - You can simply create an empty file to start. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -# runconfigs.config -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Create the tests directory and your first test -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -../tests -\end_layout - -\begin_layout Plain Layout - - ├── megatest.config -\end_layout - -\begin_layout Plain Layout - - ├── runconfigs.config -\end_layout - -\begin_layout Plain Layout - - └── tests -\end_layout - -\begin_layout Plain Layout - - └── mytest -\end_layout - -\begin_layout Plain Layout - - ├── main.sh -\end_layout - -\begin_layout Plain Layout - - └── testconfig -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Create the testconfig file for your test -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -[setup] -\end_layout - -\begin_layout Plain Layout - -runscript main.sh -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Create your test running script, main.sh -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -#!/bin/bash -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -runstep mystep1 "sleep 20;echo Done" -m "mystep1 is done" -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -test-status :state COMPLETED :status PASS -m "This is a comment" -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Run megatest and watch your run progress -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -megatest :field1 abc :field2 def :runname 2011week08.4a -runall -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -watch megatest -list-runs % -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -# OR use the dashboard -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -dashboard & -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -How to Write Tests -\end_layout - -\begin_layout Subsection -A Simple Test with one Step -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -mkdir simpletest -\end_layout - -\begin_layout Plain Layout - -cd simpletest -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Create your testconfig file -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -# testconfig -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -[setup] -\end_layout - -\begin_layout Plain Layout - -runscript main.csh -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Create the main.csh script -\end_layout - -\begin_layout Standard -Note: Using csh is NOT recommended. - Use bash, perl, ruby, zsh or anything other than csh. - We use csh here because it is popular in the EDA industry for which Megatest - was originally created. - -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -#!/bin/tcsh -x -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -# run the cpu1 simulation. -\end_layout - -\begin_layout Plain Layout - -# The step name is "run_simulation" -\end_layout - -\begin_layout Plain Layout - -# The commandline being run for this step is "runsim cpu1" -\end_layout - -\begin_layout Plain Layout - -# The logpro file to validate the output from the run is "runsim.logpro" -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -runstep run_simulation -logpro runsim.logpro "runsim cpu1" -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -test-status :state COMPLETED :status $? -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -You can now run megatest and the created test directory will contain the - new files “run_simulation.html” and “run_simulation.log”. - If you are using the dashboard you can click on the run and then push the - “View log” button to view the log file in firefox. -\end_layout - -\begin_layout Subsection -Simple Test with Multiple Steps -\end_layout - -\begin_layout Standard -To run multiple steps simply add them to the main.csh file. - Here we add a step to test “cpu2”. - The second step that tests cpu2 will only run after the step that tested - “cpu1” completes. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -#!/bin/tcsh -x -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -# run the cpu1 simulation. -\end_layout - -\begin_layout Plain Layout - -# The step name is "run_simulation" -\end_layout - -\begin_layout Plain Layout - -# The commandline being run for this step is "runsim cpu1" -\end_layout - -\begin_layout Plain Layout - -# The logpro file to validate the output from the run is "runsim.logpro" -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -runstep run_simulation_cpu1 -logpro runsim.logpro "runsim cpu1" - && -\backslash - -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -runstep run_simulation_cpu2 -logpro runsim.logpro "runsim cpu2" -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -test-status :state COMPLETED :status $? -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -Simple Test with Multiple Steps, Some in Parallel -\end_layout - -\begin_layout Subsection -The Makefile -\end_layout - -\begin_layout Standard -A good way to run steps in parallel within a single test, especially when - there are following steps, is to use the Unix Make utility. - Writing Makefiles is beyond the scope of this document but here is a minimal - example that will run “runsim cpu1” and “runsim cpu2” in parallel. - For more information on make try “info make” at the Linux command prompt. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -# Example Makefile to run two steps in parallel -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -RTLDIR=/path/to/rtl -\end_layout - -\begin_layout Plain Layout - -CPUS = cpu1 cpu2 -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -run_simulation_$(CPUS).html : $(RTLDIR)/$(CPUS) -\end_layout - -\begin_layout Plain Layout - - $(MT_MEGATEST) -runstep run_simulation_$(CPUS) -logpro runsim.logpro "runsim - $(CPUS) -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -The main.csh file -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -#!/bin/tcsh -x -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -# run the cpu1 and cpu2 simulations in parallel. - -\end_layout - -\begin_layout Plain Layout - -# The -j parameter tells make how many jobs it may run in parallel -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -make -j 2 -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -test-status :state COMPLETED :status $? -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -Simple Test with Iteration -\end_layout - -\begin_layout Standard -Since no jobs run after the cpu1 and cpu2 simulations in this test it is - possible to use iterated mode. -\end_layout - -\begin_layout Subsection -Update your testconfig file for iteration -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -[setup] -\end_layout - -\begin_layout Plain Layout - -runscript main.csh -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -[items] -\end_layout - -\begin_layout Plain Layout - -CPU cpu1 cpu2 -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Rewrite your main.csh for iteration -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -#!/bin/tcsh -x -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -# run the cpu simulation but now use the environment variable $CPU -\end_layout - -\begin_layout Plain Layout - -# to select what cpu to run the simulation against -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -runstep run_simulation -logpro runsim.logpro "runsim $CPU" -\end_layout - -\begin_layout Plain Layout - -# As of version 1.07 Megatest automatically converts a status of "0" -\end_layout - -\begin_layout Plain Layout - -# to "PASS", any other number to "FAIL" and directly uses the value of -\end_layout - -\begin_layout Plain Layout - -# a string passed in. -\end_layout - -\begin_layout Plain Layout - -$MT_MEGATEST -test-status :state COMPLETED :status $? -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Tests with Inter-test dependencies -\end_layout - -\begin_layout Standard -Sometimes a test depends on the output from a previous test or it may not - make sense to run a test is another test does not complete with status - “PASS”. - In either of these scenarios you can use the “waiton” keyword in your testconfi -g file to indicate that this test must wait on one or more tests to complete - before being launched. - In this example there is no point in running the “system” test if the “cpu” - and “mem” tests either do not complete or complete but with status “FAIL”. -\end_layout - -\begin_layout Standard -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -# testconfig for the "system" test -\end_layout - -\begin_layout Plain Layout - -[setup] -\end_layout - -\begin_layout Plain Layout - -runscript main.csh -\end_layout - -\begin_layout Plain Layout - -waiton cpu mem -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard - -\end_layout - -\begin_layout Standard -abc -\end_layout - -\begin_layout Section -\start_of_appendix -Data -\end_layout - -\begin_layout Section -References -\end_layout - -\end_body -\end_document