Updated job descriptions of server tests to be more descriptive

12 files changed, 68 insertions, 37 deletions

diff --git a/jobs/benchmarks.txt.in b/jobs/benchmarks.txt.in
index e71671f..989381e 100644
--- a/jobs/benchmarks.txt.in
+++ b/jobs/benchmarks.txt.in
@@ -3,7 +3,7 @@ _summary: Benchmark for each disk
 id: benchmarks/disk/hdparm-read
 requires: device.category == 'DISK'
 estimated_duration: 1.0
-_description: Benchmark for each disk
+_description: Raw read timing benchmark of each disk using hdparm.
 command:
 cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=DISK"'
 plugin: shell
@@ -21,7 +21,7 @@ _summary: Benchmark for each disk
 id: benchmarks/disk/hdparm-cache-read
 estimated_duration: 1.0
 requires: device.category == 'DISK'
-_description: Benchmark for each disk
+_description: Cached read timing benchmark of each disk using hdparm.
 command:
 cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=DISK"'
 plugin: shell
diff --git a/jobs/cpu.txt.in b/jobs/cpu.txt.in
index eef467c..dec5847 100644
--- a/jobs/cpu.txt.in
+++ b/jobs/cpu.txt.in
@@ -17,7 +17,7 @@ estimated_duration: 1.0
 depends: cpu/scaling_test
 command: [[ -e ${PLAINBOX_SESSION_SHARE}/scaling_test.log ]] && cat ${PLAINBOX_SESSION_SHARE}/scaling_test.log
 _description:
- Attaches the log generated by cpu/scaling_test to the results
+ Attaches the log generated by cpu/scaling_test to the results submission.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::cpu
@@ -37,7 +37,7 @@ estimated_duration: 1.0
 depends: cpu/maxfreq_test
 command: [ -e $PLAINBOX_SESSION_SHARE/maxfreq_test.log ] && cat $PLAINBOX_SESSION_SHARE/maxfreq_test.log
 _description:
- Attaches the log generated by cpu/maxfreq_test to the results
+ Attaches the log generated by cpu/maxfreq_test to the results submission.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::cpu
@@ -45,7 +45,7 @@ id: cpu/clocktest
 estimated_duration: 60.0
 command: clocktest
 _description:
- Test for clock jitter.
+ Tests the CPU for clock jitter.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::cpu
@@ -54,7 +54,7 @@ estimated_duration: 1.0
 user: root
 command: cpu_offlining
 _description:
- Test offlining CPUs in a multicore system.
+ Test offlining of each CPU core in a multicore system.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::cpu
@@ -63,7 +63,7 @@ estimated_duration: 1.0
 requires: int(cpuinfo.count) > 1 and (cpuinfo.platform == 'i386' or cpuinfo.platform == 'x86_64')
 command: cpu_topology
 _description:
- This test checks cpu topology for accuracy
+ This test checks cpu topology for accuracy between proc and sysfs.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::cpu
diff --git a/jobs/disk.txt.in b/jobs/disk.txt.in
index 94b4e11..4824d13 100644
--- a/jobs/disk.txt.in
+++ b/jobs/disk.txt.in
@@ -9,7 +9,8 @@ id: disk/detect
 estimated_duration: 0.25
 user: root
 command: disk_info
-_description: Detects and displays disks attached to the system.
+_description: 
+ Displays information about each disk detected on the system under test.
 
 unit: template
 template-unit: job
@@ -40,7 +41,9 @@ _summary: Check stats changes for each disk
 flags: deprecated
 id: disk/stats
 requires: device.category == 'DISK'
-_description: Check stats changes for each disk
+_description: 
+ This test generates some disk activity and checks the stats to ensure drive
+ activity is being recorded properly.
 command:
 cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=DISK"'
 plugin: shell
@@ -62,7 +65,8 @@ estimated_duration: 0.30
 requires:
 package.name == 'smartmontools'
 device.category == 'DISK'
-_description: SMART test
+_description: 
+ This tests the SMART capabilities of disks detected on the system.
 command:
 cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=DISK"'
 plugin: shell
@@ -83,7 +87,7 @@ id: disk/read_performance
 estimated_duration: 0.30
 requires:
 device.category == 'DISK'
-_description: Verify system storage performs at or above baseline performance
+_description: Verify system storage performs at or above a baseline speed.
 command:
 cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=DISK"'
 plugin: shell
@@ -99,12 +103,14 @@ command:
 EOF
 
 plugin: local
-_summary: Verify that storage devices, such as Fibre Channel and RAID can be detected and perform under stress.
+_summary: Verify that storage devices, such as Fibre Channel and RAID, perform under stress.
 id: disk/storage_devices
 estimated_duration: 1.0
 requires:
 device.category == 'DISK'
-_description: Verify that storage devices, such as Fibre Channel and RAID can be detected and perform under stress.
+_description: 
+ Verify that storage devices, such as Fibre Channel and RAID, perform under
+ stress without data loss or corruption.
 command:
 cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=DISK"'
 plugin: shell
diff --git a/jobs/ethernet.txt.in b/jobs/ethernet.txt.in
index 341fff4..2cc1f22 100644
--- a/jobs/ethernet.txt.in
+++ b/jobs/ethernet.txt.in
@@ -11,7 +11,9 @@ requires:
 package.name == 'pciutils'
 command: network_device_info
 estimated_duration: 1.2
-_description: Test to detect the available network controllers
+_description: 
+ Test to detect and return information about available network controllers on
+ the system under test.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::ethernet
@@ -22,7 +24,8 @@ requires:
 command: udev_resource | filter_templates -w "category=NETWORK" | awk "/interface: / { print \$2 }" | xargs -n 1 network_info
 estimated_duration: 30.0
 _description:
- This is an automated test to gather some info on the current state of your network devices. If no devices are found, the test will exit with an error.
+ Gathers some info on the current state of your network devices. If no devices
+ are found, the test will exit with an error.
 
 plugin: user-interact-verify
 category_id: 2013.com.canonical.plainbox::ethernet
@@ -56,6 +59,9 @@ requires:
 user: root
 environ: TEST_TARGET_IPERF
 command: network test -i {interface} -t iperf --fail-threshold 80 --datasize 200 --num_runs 4
+_description:
+ This test uses iperf to ensure network devices pass data at an acceptable
+ minimum percentage of advertized speed.
 
 unit: template
 template-unit: job
@@ -74,6 +80,9 @@ requires:
 user: root
 environ: TEST_TARGET_IPERF
 command: network test -i {interface} -t iperf --iperf3 --fail-threshold 80 --cpu-load-fail-threshold 90 --datasize 200 --num_runs 4
+_description:
+ This test uses iperf3 to ensure network devices pass data at an acceptable
+ minimum percentage of advertized speed.
 
 unit: template
 template-unit: job
diff --git a/jobs/info.txt.in b/jobs/info.txt.in
index 0379122..3d074b1 100644
--- a/jobs/info.txt.in
+++ b/jobs/info.txt.in
@@ -93,13 +93,14 @@ requires: package.name == 'usbutils'
 user: root
 command: lsusb -vv | iconv -t 'utf-8' -c
 estimated_duration: 0.700
-_description: List USB devices
+_description: Attaches a list of detected USB devices.
 
 id: meminfo_attachment
 plugin: attachment
 category_id: 2013.com.canonical.plainbox::info
 command: cat /proc/meminfo
 estimated_duration: 0.043
+_description: Attaches info on system memory as seen in /proc/meminfo.
 
 id: modprobe_attachment
 plugin: attachment
@@ -137,7 +138,7 @@ plugin: attachment
 category_id: 2013.com.canonical.plainbox::info
 command: find /etc/sysctl.* -name \*.conf | xargs cat
 estimated_duration: 0.014
-_description: attaches the contents of various sysctl config files.
+_description: Attaches the contents of various sysctl config files.
 _summary: Attach sysctl configuration files.
 
 id: sysfs_attachment
@@ -212,7 +213,7 @@ plugin: local
 _summary: SATA/IDE device information.
 id: info/hdparm
 estimated_duration: 1.0
-_description: SATA/IDE device information.
+_description: Attaches SATA/IDE device information reported by hdparm.
 requires:
 package.name == 'hdparm'
 device.category == 'DISK'
@@ -380,7 +381,9 @@ plugin: attachment
 category_id: 2013.com.canonical.plainbox::info
 id: info/kvm_output
 estimated_duration: 0.1
-_description: Attaches the debug log from the virtualization run
+_description: 
+ Attaches the debug log from the virtualization/kvm_check_vm test
+ to the results submission.
 command: [ -f $PLAINBOX_SESSION_SHARE/virt_debug ] && cat $PLAINBOX_SESSION_SHARE/virt_debug
 
 id: kernel_cmdline_attachment
diff --git a/jobs/memory.txt.in b/jobs/memory.txt.in
index 0f66efd..2a8f910 100644
--- a/jobs/memory.txt.in
+++ b/jobs/memory.txt.in
@@ -17,5 +17,8 @@ requires:
 uname.name == 'Linux'
 command: memory_test
 _description:
- Test and exercise memory.
+ Test to perfrom some basic stress and exercise of system memory. This test
+ also includes an over-commit function to force swapping to disk, thus SUTs
+ should have suitably large swap files for the amount of RAM they have
+ installed.
 
diff --git a/jobs/miscellanea.txt.in b/jobs/miscellanea.txt.in
index 5a59d7a..249c638 100644
--- a/jobs/miscellanea.txt.in
+++ b/jobs/miscellanea.txt.in
@@ -15,7 +15,9 @@ depends:
 estimated_duration: 1.0
 command: true
 _description:
- A meta-job depending on the resources needed for a valid submission.
+ A meta-job that verifies the data necessary for a complete result
+ submission are present. Failure indicates that the results are incomplete
+ and may be rejected.
 
 plugin: manual
 category_id: 2013.com.canonical.plainbox::miscellanea
@@ -65,7 +67,7 @@ category_id: 2013.com.canonical.plainbox::miscellanea
 id: miscellanea/fwts_results.log
 command:
 [[ -e ${PLAINBOX_SESSION_SHARE}/fwts_results.log ]] && cat ${PLAINBOX_SESSION_SHARE}/fwts_results.log
-_description: Attaches the FWTS results log to the submission
+_description: Attaches the miscellanes/fwts_test results log to the submission.
 
 plugin: attachment
 category_id: 2013.com.canonical.plainbox::miscellanea
@@ -83,7 +85,9 @@ requires: package.name == 'ipmitool'
 user: root
 command: ipmi_test
 _description:
- This will run some basic connectivity tests against a BMC, verifying that IPMI works.
+ This will run some basic commands in-band against a BMC, verifying that IPMI
+ works. Use of MAAS to deploy the system implicitly tests out-of-band BMC
+ control.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::miscellanea
@@ -92,7 +96,8 @@ id: miscellanea/boot_mode
 requires:
 cpuinfo.platform in ("i386", "x86_64", "aarch64")
 _summary: EFI-mode boot test
-_description: Succeeds when booted in EFI mode; fails otherwise
+_description: 
+ Test to verify that the system booted in EFI mode rather than Legacy/BIOS mode.
 command:
 if [ -d "/sys/firmware/efi" ] ; then
 echo "System booted in EFI mode"
@@ -109,7 +114,8 @@ estimated_duration: 0.5
 user: root
 command: bmc_info
 _description:
- This will gather some info about the BMC itself for diagnostic purposes.
+ This will gather some info about the BMC itself for diagnostic purposes. This
+ will not works on non-IPMI systems like AMT and blade/sled type systems.
 _summary:
 Gather BMC Identification info
 
diff --git a/jobs/optical.txt.in b/jobs/optical.txt.in
index 20ba986..f9a4237 100644
--- a/jobs/optical.txt.in
+++ b/jobs/optical.txt.in
@@ -3,7 +3,7 @@ category_id: 2013.com.canonical.plainbox::optical
 id: optical/detect
 requires: device.category == 'CDROM'
 estimated_duration: 1.2
-_description: Test to detect the optical drives
+_description: Detects optical drives (CD/DVD) attached to the system.
 command:
 cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=CDROM"' | sed '/^$/d'
 $vendor $product
@@ -42,7 +42,8 @@ id: optical/read-automated
 estimated_duration: 1.0
 requires:
 device.category == 'CDROM'
-_description: Automated optical read test.
+_description: 
+ Automated test to read a data CD/DVD and ensure the optical drive works properly.
 command:
 cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=CDROM"'
 plugin: shell
diff --git a/jobs/power-management.txt.in b/jobs/power-management.txt.in
index 26256af..a7746b0 100644
--- a/jobs/power-management.txt.in
+++ b/jobs/power-management.txt.in
@@ -166,7 +166,7 @@ user: root
 command: hwclock -r
 estimated_duration: 0.02
 _description:
- Verify that the Real-time clock (RTC) device functions properly, if present
+ Verify that the Real-time clock (RTC) device functions properly, if present.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::power-management
diff --git a/jobs/stress.txt.in b/jobs/stress.txt.in
index 64b064f..f103cd7 100644
--- a/jobs/stress.txt.in
+++ b/jobs/stress.txt.in
@@ -7,8 +7,9 @@ requires:
 user: root
 command: num_vm=$(awk '/MemTotal/ {x=$2/262144; print ((x == int(x)) ? x : int(x) +1)}' /proc/meminfo); vm_bytes=$(($(awk '/MemTotal/ {print int($2/1024)}' /proc/meminfo)/$num_vm/4))M; stress --cpu `cpuinfo_resource | awk '/count:/ {print $2}'` --vm $num_vm --vm-bytes $vm_bytes --timeout 7200s
 _description:
- PURPOSE:
- Create jobs that use the CPU as much as possible for two hours. The test is considered passed if the system does not freeze.
+ Simulate high system load using the 'stress' tool to exercise the CPU for
+ several hours. The test is considered passed if the system does not freeze or
+ abend.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::stress
diff --git a/jobs/usb.txt.in b/jobs/usb.txt.in
index 7a60bfa..897ea8f 100644
--- a/jobs/usb.txt.in
+++ b/jobs/usb.txt.in
@@ -182,9 +182,9 @@ user: root
 estimated_duration: 45.0
 command: removable_storage_test -l usb && removable_storage_test -s 268400000 usb
 _description:
- This is an automated version of usb/storage-automated and assumes that the
- server has usb storage devices plugged in prior to checkbox execution. It
- is intended for servers and SRU automated testing.
+ Tests USB 2.0 or 1.1 ports on a system by doing write/read/compare tests on
+ randomly created data. It requires that a USB stick is plugged into an
+ available USB port before running the certification suite.
 
 plugin: shell
 category_id: 2013.com.canonical.plainbox::usb
@@ -195,9 +195,10 @@ requires:
 estimated_duration: 45.0
 command: removable_storage_test -l usb && removable_storage_test -s 268400000 -m 500000000 usb --driver xhci_hcd
 _description:
- This is an automated version of usb3/storage-automated and assumes that the
- server has usb 3.0 storage devices plugged in prior to checkbox execution. It
- is intended for servers and SRU automated testing.
+ Tests USB 3.0 ports on a system by doing write/read/compare tests on
+ randomly created data. It requires that a USB stick is plugged into an
+ available USB port before running the certification suite. Additionally, it
+ will only work with USB sticks and ports rated for USB 3.0 speeds or faster.
 
 plugin: manual
 category_id: 2013.com.canonical.plainbox::usb
diff --git a/jobs/virtualization.txt.in b/jobs/virtualization.txt.in
index 5a3ce76..5edda6b 100644
--- a/jobs/virtualization.txt.in
+++ b/jobs/virtualization.txt.in
@@ -10,7 +10,8 @@ requires:
 virtualization.kvm == 'supported'
 command: virtualization kvm --debug --log-file=$PLAINBOX_SESSION_SHARE/virt_debug
 _description:
- Test to check that a cloud image boots and works properly with KVM
+ Verifies that a KVM guest can be created and booted using an Ubuntu Server
+ cloud image.
 _summary:
 Verify KVM VM boots