tests/README

   1 eCryptfs Test Suite
   2
   3 Follow these steps when adding a new test:
   4
   5  NOTE: This guide primarily focuses on kernel test cases. If you're writing a
   6        userspace test case, substitute all mentions of tests/kernel/ with
   7        tests/userspace/ and pay attention to any other kernel-specific
   8        instructions.
   9
  10  1) Pick a name for the new test. This guide will be using the test case name
  11     "mmap-close", but you'll need to substitute in the name of your own test
  12     case.
  13
  14     If it is a reproducer for a bug, consider using the bug tracker and bug
  15     number. For example, lp-469664 is the test for
  16     https://launchpad.net/bugs/469664.
  17
  18     Otherwise, pick a short, but descriptive, name for the test. For example,
  19     trunc-file is the name of a test that excercises file truncation.
  20
  21  2) Copy the skeleton test script to the appropriate test directory. In this
  22     guide, we're creating a kernel test so copy it to the tests/kernel/
  23     directory:
  24
  25     ---
  26     $ cp tests/new.sh tests/kernel/mmap-close.sh
  27     ---
  28
  29  3) Update the information in the comments at the top of your new test case.
  30     Specifically, the words below in all caps need to be modified:
  31
  32     ---
  33     # FILENAME: Test for BUG_URL|LIST_URL|DESCRIPTION
  34     # Author: FIRST LAST <USER@DOMAIN>
  35     #
  36     # Copyright (C) YEAR COPYRIGHT_HOLDER
  37     ---
  38
  39     In this case, we end up with something along these lines:
  40
  41     ---
  42     # mmap-close.sh : Test for catching regressions when applications do this:
  43     #
  44     #                 open() -> mmap() -> *close()* -> dirty mapping -> munmap()
  45     #
  46     #                 Past regressions have been reported in these bugs:
  47     #
  48     #                 https://bugs.launchpad.net/bugs/870326
  49     #                 https://bugs.launchpad.net/bugs/1047261
  50     # Author: Tyler Hicks <tyhicks@canonical.com>
  51     ---
  52
  53  4) Now you can start writing the test. You'll probably need to set up a basic
  54     eCryptfs mount. You can do that by pasting in these sequence of helper
  55     functions after the "# TEST" line in your new test case:
  56
  57     ---
  58     # TEST
  59     etl_add_keys || exit
  60     etl_lmount || exit
  61     etl_mount_i || exit
  62     test_dir=$(etl_create_test_dir) || exit
  63     ---
  64
  65     This is probably a good time to introduce the library of helper functions.
  66     It can be found in tests/lib/etl_funcs.sh. Take a look at the functions
  67     available and feel free to add any new functions if you feel like they would
  68     benefit multiple test cases.
  69
  70  5) At this point, we have a lower filesystem mounted, an eCryptfs filesystem
  71     mounted on top of it, and a test directory created inside of the eCryptfs
  72     mount. We'll need to properly tear all of that down when the test case
  73     exits, so update the test_cleanup() function accordingly:
  74
  75     ---
  76     test_cleanup()
  77     {
  78         etl_remove_test_dir $test_dir
  79         etl_umount
  80         etl_lumount
  81         etl_unlink_keys
  82         exit $rc
  83     }
  84     trap test_cleanup 0 1 2 3 15
  85     ---
  86
  87  6) Now we are ready to implement the actual test. If it is simple enough to do
  88     with basic bash commands, as is the case for lp-469664.sh, simply add those
  89     commands and skip to step 11).
  90
  91     If you need to write a C (or possibly Python) program, proceed to step 7).
  92
  93  7) Create a directory to hold the C source file(s) and any other data files
  94     that you'll need. It should be named after your test case.
  95
  96     ---
  97     $ mkdir tests/kernel/mmap-close/
  98     ---
  99
 100  8) Create a new file, inside that directory, called test.c and implement the
 101     test case in the new file. Be sure to add a header, including the GPLv2
 102     text, similar to what is in the example test script that was modified in
 103     step 3).
 104
 105  9) Update the test script (mmap-close.sh) to call the test binary after the
 106     environment setup stage:
 107
 108     ---
 109     ${test_script_dir}/mmap-close/test || exit
 110     ---
 111
 112  10) Add a line to tests/kernel/Makefile.am to build test.c:
 113
 114     ---
 115     mmap_close_test_SOURCES = mmap-close/test.c
 116     ---
 117
 118     And add the test binary to the noinst_PROGRAMS list:
 119
 120     ---
 121     noinst_PROGRAMS = directory-concurrent/test \
 122                       ...
 123                       mmap-close/test \
 124                       ...
 125                       trunc-file/test
 126
 127     ---
 128
 129  11) Add a line to tests/kernel/Makefile.am to place the new test script in the
 130     dist_noinst_SCRIPTS list:
 131
 132     ---
 133     dist_noinst_SCRIPTS = directory-concurrent.sh \
 134                           ...
 135                           mmap-close.sh \
 136                           ...
 137                           trunc-file.sh
 138
 139     ---
 140
 141  12) Finally, add the new test script to the appropriate list in
 142      tests/kernel/tests.rc. There are only two lists - safe and destructive.
 143      Safe means that the tests aren't likely to cause a kernel oops or other
 144      unrecoverable error. Everything else goes in the destructive list.
 145
 146 This was a quick introduction into creating a new test case. Look at other
 147 existing test cases for more examples.