File docs/megatest.wiki artifact 50f0ba7bf3 part of check-in 513285e117
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> <meta name="generator" content="http://www.nongnu.org/elyxer/"/> <meta name="create-date" content="2011-09-20"/> <link rel="stylesheet" href="http://www.nongnu.org/elyxer/lyx.css" type="text/css" media="screen"/>
Converted document
</head> <body>Matthew Welland
Sept. 20,
Email: matt@kiatoa.com.
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.
Document Revision History
Version | Author | Description | Date |
v1.25 | matt | converted to new document format |
|
1 Introduction
1.1 Megatest design philosophy
1.2 Megatest architecture
2 Installation
2.1 Dependencies
2.2 Build and Install
3 Setup
3.1 Create megatest.config
# Fields are the keys under which your test runs are organized fields field1 TEXT field2 TEXT jobtools # The launcher launches jobs to the local or remote hosts, # the job is managed on the target host by megatest, # comment out launcher to run local only. An example launcher # "nbfake" can be found in the utils directory. launcher nbfake # The disks section specifies where the tests will be run. As you # run out of space in a partition you can add additional disks # entries. # Format is: # name /path/to/area disks disk1 /tmp
3.2 Create runconfigs.config
# runconfigs.config
3.3 Create the tests directory and your first test
../tests ├── megatest.config ├── runconfigs.config └── tests └── mytest ├── main.sh └── testconfig
3.4 Create the testconfig file for your test
setup runscript main.sh
3.5 Create your test running script, main.sh
#!/bin/bash $MT_MEGATEST -runstep mystep1 "sleep 20;echo Done" -m "mystep1 is done" $MT_MEGATEST -test-status :state COMPLETED :status PASS -m "This is a comment"
3.6 Run megatest and watch your run progress
megatest :field1 abc :field2 def :runname 2011week08.4a -runall watch megatest -list-runs % # OR use the dashboard dashboard &
4 How to Write Tests
4.1 A Simple Test with one Step
mkdir simpletest cd simpletest
4.2 Create your testconfig file
# testconfig setup runscript main.csh
4.3 Create the main.csh script
#!/bin/tcsh -x # run the cpu1 simulation. # The step name is "run_simulation" # The commandline being run for this step is "runsim cpu1" # The logpro file to validate the output from the run is "runsim.logpro" $MT_MEGATEST -runstep run_simulation -logpro runsim.logpro "runsim cpu1" $MT_MEGATEST -test-status :state COMPLETED :status $?
4.4 Simple Test with Multiple Steps
#!/bin/tcsh -x # run the cpu1 simulation. # The step name is "run_simulation" # The commandline being run for this step is "runsim cpu1" # The logpro file to validate the output from the run is "runsim.logpro" $MT_MEGATEST -runstep run_simulation_cpu1 -logpro runsim.logpro "runsim cpu1" && \ $MT_MEGATEST -runstep run_simulation_cpu2 -logpro runsim.logpro "runsim cpu2" $MT_MEGATEST -test-status :state COMPLETED :status $?
5 Simple Test with Multiple Steps, Some in Parallel
5.1 The Makefile
# Example Makefile to run two steps in parallel RTLDIR=/path/to/rtl CPUS = cpu1 cpu2 run_simulation_$(CPUS).html : $(RTLDIR)/$(CPUS) $(MT_MEGATEST) -runstep run_simulation_$(CPUS) -logpro runsim.logpro "runsim $(CPUS)
5.2 The main.csh file
#!/bin/tcsh -x # run the cpu1 and cpu2 simulations in parallel. # The -j parameter tells make how many jobs it may run in parallel make -j 2$MT_MEGATEST -test-status :state COMPLETED :status $?
6 Simple Test with Iteration
6.1 Update your testconfig file for iteration
6.2 Rewrite your main.csh for iteration
#!/bin/tcsh -x# run the cpu simulation but now use the environment variable $CPU# to select what cpu to run the simulation against$MT_MEGATEST -runstep run_simulation -logpro runsim.logpro "runsim $CPU"# As of version 1.07 Megatest automatically converts a status of "0"# to "PASS", any other number to "FAIL" and directly uses the value of# a string passed in.$MT_MEGATEST -test-status :state COMPLETED :status $?
6.3 Tests with Inter-test dependencies
# testconfig for the "system" testrunscript main.cshwaiton cpu mem
7 Dashboard


8 Reference
8.1 Configuration file Syntax
8.1.1 Sections
8.1.2 Variables
VARX has this value
8.1.3 Includes
8.1.4 Setting a variable by running a command
VARNAME system ls /tmp
8.1.5 Notes
- Some variables are infered as lists. Each token on the line separated by whitespace will be member of the list.
- Comments (lines starting with #) and blank lines are ignored.
8.2 Environment variables
Variable | Purpose |
MT_CMDINFO | Conveys test variables to the megatest test runner. |
MT_TEST_RUN_DIR | Directory assigned by megatest for the test to run. |
MT_TEST_NAME | Name of the test, corrosponds to the directory name under tests. |
MT_ITEM_INFO | Iterated tests will set this to a sequence of key/values ((KEY val) ...) |
MT_RUN_AREA_HOME | Directory where megatest was launched from and where the tests code can be found |
MT_RUNNAME | Name of this run as set by the :runname parameter |
MT_MEGATEST | Path/Filename to megatest executable. Found either from called path or but using the “exectuable” keyword in the setup section. |
<field1> .... | The field values as set on the megatest -runall command line (e.g. :field1 abc) |
8.3 megatest.config
section | variable | value | required | comment |
setup | max_concurrent_jobs | if variable is not defined no limit on jobs | no | |
executable | full path to megatest binary | no | Use only if necessary, megatest will extract the location from where it used to launch and add append that to the PATH for test runs. | |
runsdir | full path to where the link tree to all runs will be created | no | Because your runs may be spread out over several disk partitions a central link tree is created to make finding all the runs easy. | |
fields | string of letters, numbers and underscore | string of letters, numbers and underscore | at least one | |
jobtools | launcher | command line used to launch jobs - the job command (megatest -execute) will be appended to this | no | |
workhosts | list of hostnames to run jobs on NOT SUPPORTED RIGHT NOW | n/a | ||
env-override | string of letters, numbers and underscore | any string | no | These are set on the test launching machine, not the test running machine. Typical usage is to control the host or run queue for launching tests. These values will not be seen by the test when it runs. |
disks | string of letters, numbers and underscore | a valid path writable by the test launching process and by the test process | yes | The disk usage balancing algorithm is to choose the disk with the least space for each test run. |
8.4 runconfigs.config file
section | variable | value | required? | comment |
default | string of letters, numbers and underscore | any | no | variables set in this section will be available for all runs, defining the same variable in another section will override the value from the default section |
field1value/field2value... | string of letters, numbers and underscore | any | no | the values in this section will be set for any run where field1 is field1value, field2 is field2value and fieldN is fieldNvalue. |
# runconfigs.config default ENCRYTION true megacorp/india TESTPATH /nfs/testing/megacorp_runs femtocorp/cook_islands ENCRYTION false TESTPATH /afs/kiatoa/testing/cook_islands femtocorp/new_zealand TESTPATH /afs/kiatoa/testing/new_zealand megacorp/new_zealand TESTPATH /nfs/testing/megacorp_runs
8.5 Writing tests
8.5.1 testconfig file
section | variable | value | required? | comments |
setup | runscript | name of script to execute for this test | yes | The script must be executable and either provide the full path or put a copy at the top of your test directory |
requirements | waiton | list of valid test names | no | This test will not run until the named tests are state completed and status PASS |
items | any valid | list of values | no | The test will be repeated once for each item with the variable name set to the value. If there is more than one variable then the test will be run against all unique combinations of the values |
8.5.2 Command line
switch or param | parameter | purpose | comments |
-h | brief help | ||
-runall | run all tests | ||
-runtests | test1,test2,... | run one or more tests | |
-step | stepname | record a step | requires :state and :status |
-test-status | record the test status | requires :state and :status | |
-setlog | logfilename | set the logfile name for a test | path is assumed to be relative to the test run directory |
-set-toplog | logfilename | set the logfile name for the top test in an iterated test run | each sub test can have its own logfile set |
-m | “comment” | sets a comment for the step, test or run | |
:runname | a-zA-Z0-9_-+ | directory in which this run will be stored in the test run area | |
:state | any value | Set the step or test state, this is stored in the state field in the steps or tests table respectively | For tests Megatest recognises “INCOMPLETE”, “COMPLETE” |
:status | any value | Set the step or test status, this is stored in the status field in the steps or tests table respectively | For tests Megatest recognises “PASS”, “FAIL”, and “CHECK” |
-list-runs | any value, % is wildcard | Respects -itempatt and -testpatt for filters | |
-testpatt | any value, % is wildcard | ||
-itempatt | any value, % is wildcard | ||
-showkeys | Print the keys being used for this database | ||
-force | Test will not re-run if in the “PASS”, “CHECK” or “KILLED”, using -force will force the run to be launched. | WARNING: The -force switch will bypass any “waiton” dependencies. | |
-xterm | Launch an xterm instead of run the test. The xterm will have the environment that the test would see. | ||
-remove-runs | Remove a run, test or subtest from the database and the disk. Cannot be undone. Requires -testpatt, -itempatt, :runname and all keys be specified. | ||
Test helpers | |||
-runstep | Used inside a test to run a step, record the start and end of the step and optionally analyze the output using logpro. | ||
-logpro | If using logpro to asses the PASS/FAIL status of the step you specify the logpro file with this parameter. |