Skip to content

Quickstart atf sh test

Jump to bottom
Julio Merino edited this page Jul 3, 2016 · 2 revisions

Writing an ATF test in Bourne shell script

The ATF test framework provides a library and API for writing test programs. Currently, ATF programs can only be written in C, C++, or Bourne shell script.

Example ATF test - Bourne shell script

The following example consists of one shell script, atf_tests1.sh, and one Kyuafile which references the shell script. The shell script and the Kyuafile must be in the same directory. Also, you must grant executable permissions to atf_tests1.sh.

atf_tests1.sh - test program with multiple test cases

#! /usr/bin/env atf-sh

# #!/bin/sh should not be invoked directly.
# We must call atf-sh which is a wrapper around /bin/sh.
# See libatf-sh.subr for the library functions inside ATF
# called by atf-sh.

# An ATF test case is defined by doing the following:
#
# 1.  Call atf_test_case() function with name of test case as an argument.
# 2.  Implement _head(), _body() methods.
# 3.  Implement a _cleanup() method [OPTIONAL].
# 4.  Add to atf_init_test_cases() method.
#
# NOTES:
# * An ATF test program *cannot* have 'exit' or 'return' statements.
#   This will break functions in libatf-sh.subr.
#   Instead, use atf_pass(), atf_fail(), atf_skip(), atf_check()
#   and assume that the test case will terminate after one of these functions
#   is invoked.

#
# test1
#
atf_test_case test1

test1_head()
{
    atf_set "descr" "Test 1 which succeeds"
}

test1_body()
{
    if [ 1 -eq 1 ];
    then
        atf_pass
    else
        atf_fail "Not equal"
    fi
}

#
# test2
#
atf_test_case test2
test2_head()
{
    atf_set "descr" "Test 2 which fails"
}
test2_body()
{
    rm /nonexistentfile
}

#
# test3
#
atf_test_case test3 cleanup
test3_head()
{
    atf_set "descr" "Test 3 which fails"
}
test3_body()
{
    rm /nonexistentfile
    if [ $? -ne 0 ]; then
        atf_fail "Could not remove /nonexistentfile"
    else
        atf_pass "Could not remove /nonexistentfile"
    fi 
}
test3_cleanup()
{
    echo "Do some cleanup here"
}

#
# test4
#
atf_test_case test4

test4_head()
{
    atf_set "descr" "Test 4 which skips"
}

test4_body()
{
    atf_skip "Skipping this test"
}

#
# We must define a method atf_init_test_cases()
# which specifies all the test cases which will
# be run from this file. 
#
atf_init_test_cases()
{
    atf_add_test_case test1
    atf_add_test_case test2
    atf_add_test_case test3
    atf_add_test_case test4
}

Kyuafile

-- Comments in Kyuafiles must start with two hyphens

-- The syntax version must be defined to 2 at the
-- beginning of all Kyuafiles. 
syntax(2)

-- The name of the test suite must be defined.
test_suite('suite2')

-- This specifies the test programs
atf_test_program{name='atf_tests1.sh'}

Listing the tests

To list the tests which will be run, type:

kyua list

The output will look like this:

atf_tests1.sh:test1
atf_tests1.sh:test2
atf_tests1.sh:test3
atf_tests1.sh:test4

If this does not work, double-check that atf_tests1.sh is executable and, if it is, run it as ./atf_tests1.sh -l to get some diagnostic information.

Running the tests

To run the all tests, type:

kyua test

The output of the test run will look like:

atf_tests1.sh:test1  ->  passed  [0.014s]
atf_tests1.sh:test2  ->  failed: Test case body returned a non-ok exit code, but this is not allowed  [0.015s]
atf_tests1.sh:test3  ->  failed: Could not remove /nonexistentfile  [0.015s]
atf_tests1.sh:test4  ->  skipped: Skipping this test  [0.014s]

Results file id is usr_home_crodrigues_kyua-quickstart_kyua.wiki_QuickStart.20141009-003125-216279
Results saved to /home/crodrigues/.kyua/store/results.usr_home_crodrigues_kyua-quickstart_kyua.wiki_QuickStart.20141009-003125-216279.db

2/4 passed (2 failed)

If this does not work, double-check that atf_tests1.sh is executable and, if it is, run it as ./atf_tests1.sh -l to get some diagnostic information.

To run only the first test, type:

kyua test atf_tests1.sh:main

The output of the test run will look like:

atf_tests1.sh:test1  ->  passed  [0.014s]

Results file id is usr_home_crodrigues_kyua-quickstart_kyua.wiki_QuickStart.20141009-003148-760012
Results saved to /home/crodrigues/.kyua/store/results.usr_home_crodrigues_kyua-quickstart_kyua.wiki_QuickStart.20141009-003148-760012.db

1/1 passed (0 failed)

To run the third test case outside of kyua (for debugging purposes), type:

./atf_tests1.sh test3

The output of the test will look like:

atf_tests1.sh: WARNING: Running test cases without atf-run(1) is unsupported
atf_tests1.sh: WARNING: No isolation nor timeout control is being applied; you may get unexpected failures; see atf-test-case(4)
rm: /nonexistentfile: No such file or directory
failed: Could not remove /nonexistentfile

Generating test reports

After running the tests, you can generate test reports.

  • To generate a report in text format, type:

      kyua report

  • To generate a report in HTML format, type:

      kyua report-html

  • To generate a report in JUnit XML, type:

      kyua report-junit

Further references

Clone this wiki locally