Editing C&I Wiki Portal/ToolsDevelopmentGuideline (section)

==== Job Files ====
As discussed before, job files contain the descriptions that define each test case or unit of test.  
===== Basic Job Description =====
An example job description looks like this:

<pre>
plugin: shell
name: memory/ocp/stress_30min
user: root
command: stressapptest -s 1800
_description:
 Test and exercise memory.
</pre>

This is a very basic example that contains most of the common KEY:VALUE pairs that are used to describe a test.
;plugin
:Plugins are the type of job to perform.  
:'''shell''' is a fully automated job that is executed by the test harness automatically with no user intervention.  
:'''manual''' is a test/job that requires the user to perform some task and verify the results.
:'''user-interact''' which also requires the user to initiate the test with the PASS or FAIL results being automatically determined by Checkbox
:'''user-interact-verify''' requires the user to initiate the test AND validate the results, choosing PASS or FAIL afterwards.
;name
:This is a descriptive name of the test.  In this case, the hierarchy means that it's a Memory test that is part of the OCP Specific tests and the test case is 'stress_30min'
;user 
:Some jobs can be run as an alternate user (in fact, some require this).  So specifying '''root''' here will tell Checkbox to run the '''command''' as the root user (essentially using sudo to elevate privileges for this one test only).
;command
:This is the command to perform.  This item can be in-line code (like a bash oneliner or test) or the name of a command that is in the bin/ directory.
;_description
:This is a text description of the job.  For a Manual job, '''description''' would list the steps necessary to perform the test.  For an automated test, this is just a summary of what the test does.

===== Meta-Jobs =====
There are also things we refer to as "Metajobs".  These jobs are actually run early on and are simply used to generate jobs on the fly.  In general, you would use a metajob to create separate jobs for multiple pieces of the same hardware.  In the following example, we have a metajob that creates a separate storage test for any disk device (NON-USB) discovered.

<pre>
plugin: local
name: disk/ocp/io_stress
requires:
 device.category == 'DISK'
 package.name == 'stressapptest'
_description: Verify that storage devices, such as Fibre Channel and RAID can be detected and perform under stress.
command:
 cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=DISK"'
 plugin: shell
 name: disk/ocp/io_stress_`ls /sys$path/block`
 user: root
 requires:
  device.path == "$path"
  block_device.`ls /sys$path/block`_state != 'removable'
 description: Disk I/O stress test for $product
 command: disk_stress `ls /sys$path/block | sed 's|!|/|'`
 EOF
</pre>

Note the differences between a Metajob and a normal Job.
;Plugin
:'''local''' is a special plugin that tells Checkbox to run this job as soon as the tool starts. This means this job is executed well before the user ever sees a Suite or Test Selection screen.
;requires
:This job also introduces the '''requires''' directive.  This means that the following conditions must be met before the job will be run.  
:Also note that you can specify multiple requirements by placing each one on a new line with a single-space indention.
;Command
:In the basic example, I mentioned that a '''Command''' can be embedded shell code.  This is an example of that embedded shell code.  This runs the shell code that follows.  In this example, it cats all the text between the 'cat' line and the 'EOF' marker (which looks exactly like the Basic Job Description) and pipes all that through the 'run-templates' helper tool which creates on-the-fly jobs.  In this case, 'run-templates' also executes the udev-resource resource gathering script and ensures that child jobs are ONLY created for hardware devices that fit into the DISK category (so we don't create these Disk jobs for network devices or CPUs).