Diff for /wikisrc/tutorials/atf.mdwn between versions 1.1 and 1.2

version 1.1, 2010/09/01 20:59:24 version 1.2, 2010/09/02 22:59:38
Line 20  and Line 20  and
   
 **IMPORTANT: Do not take anything for granted, SPECIALLY if you have previously  **IMPORTANT: Do not take anything for granted, SPECIALLY if you have previously
 worked with and/or have seen src/regress/.  Your assumptions are most likely  worked with and/or have seen src/regress/.  Your assumptions are most likely
 wrong.**  incorrect.**
   
 ## Test programs vs. test cases  ## Test programs vs. test cases
   
Line 64  Then, you could define the following tes Line 64  Then, you could define the following tes
 * bin/ls/integration_test.sh: Provides "black box" test cases for the binary  * bin/ls/integration_test.sh: Provides "black box" test cases for the binary
   itself.  These would be named lflag, lflag_and_Fflag, no_flags, no_files, etc.    itself.  These would be named lflag, lflag_and_Fflag, no_flags, no_files, etc.
   
 Try to keep your test case names as descriptive as possible.  Try to keep your test case names as descriptive as possible so that they do not
   require comments to explain what they intend to test.
   
   ## Installation of test programs: the why and the where
   
   Test programs get installed into the /usr/tests/ hierarchy.  The main reason for
   doing that is to allow *any* user to test his system and to be able to convince
   himself that everything is working correctly.
   
   Imagine that you install NetBSD-current on a public-facing machine that has some
   particular hardware only supported in the bleeding-edge source tree.  In this
   scenario, you, as the administrator, could just go into /usr/tests/, run the
   tests and know immediately if everything is working correctly in your
   software+hardware combination or not.  No need to rely on promises from the
   vendor, no need to deal with a source tree, no need to have a compiler
   installed...
   
   So, that's the theory.  Now, how does this map to our source tree?
   
   At the moment, the source test programs are located somewhere under src/tests/.
   Say, for example, that you have the src/tests/bin/ls/ui_test.c source file.
   This Makefile in src/tests/bin/ls/ will take this source file and generate a
   ui_test binary.  The Makefile will also generate an Atffile.  Both files (the
   ui_test binary and the Atffile) will later be installed to /usr/tests/bin/ls/
   
 ## Adding a new test  ## Adding a new test
   
 To add a new *test case* to the source tree, look for any test program in  To add a new *test case* to the source tree, look for any test program in
 src/tests/ that can assimilate it.  If you find such a program, just add the  src/tests/ that can assimilate it.  If you find such a program, just add the
 test case to it; no other changes are required.  Otherwise, you will have to  test case to it: no other changes are required so your life is easy.  Otherwise,
 create a new test program.  you will have to create a new test program.
   
 To add a new *test program* to the source tree:  To add a new *test program* to the source tree:
   
Line 105  If the subdirectory does not exist: Line 128  If the subdirectory does not exist:
   
 ### Makefile template  ### Makefile template
   
     # $NetBSD$      # $NetBSD: atf.mdwn,v 1.1 2010/09/01 20:59:24 jmmv Exp $
   
     .include <bsd.own.mk>      .include <bsd.own.mk>
   
Line 122  If the subdirectory does not exist: Line 145  If the subdirectory does not exist:
   
     .include <bsd.test.mk>      .include <bsd.test.mk>
   
   ### Atffile template
   
   What is an Atffile?  An Atffile is the atf-run counterpart of a "Makefile".
   Given that atf tests *do not rely on a toolchain*, they cannot use make(1) to
   script their execution as the old tests in src/regress/ did.
   
   The Atffiles, in general, just provide a list of test programs in a particular
   directory and the list of the subdirectories to descend into.
   
   Atffiles are automatically generated by bsd.test.mk, so in general you will not
   have to deal with them.  However, if you have to provide one explicitly, they
   follow the following format:
   
       Content-Type: application/X-atf-atffile; version="1"
   
       prop: test-suite = NetBSD
   
       tp: first_test
       tp: second_test
       tp-glob: optional_*_test
       tp: subdir1
       tp: subdir2
   
 ## C test programs  ## C test programs
   
 ### Template  ### Template
   
   The following code snippet provides a C test program with two test cases:
   
     #include <atf-c.h>      #include <atf-c.h>
   
     ATF_TC(tc, my_test_case);      ATF_TC(tc, my_test_case);
Line 145  If the subdirectory does not exist: Line 193  If the subdirectory does not exist:
             atf_tc_fail("Condition not met!"); /* Explicit failure. */              atf_tc_fail("Condition not met!"); /* Explicit failure. */
     }      }
   
       ATF_TC_WITHOUT_HEAD(tc, another_test_case);
       ATF_TC_BODY(tc, another_test_case)
       {
           /* Do more tests here... */
       }
   
     ATF_TP_ADD_TCS(tp)      ATF_TP_ADD_TCS(tp)
     {      {
         ATF_TP_ADD_TC(tp, my_test_case);          ATF_TP_ADD_TC(tp, my_test_case);
           ATF_TP_ADD_TC(tp, another_test_case);
     }      }
   
   This program needs to be linked against libatf-c as described below.  Once
   linked, the program automatically gains a main() method that provides a
   consistent user interface to all test programs.  You are simply not inteded to
   provide your own main method, nor to deal with the command-line of the
   invocation.
   
 ### How to build  ### How to build
   
 To build a C test program, append the name of the test program (without the .c  To build a C test program, append the name of the test program (without the .c
Line 169  For example: Line 230  For example:
   
 ### Template  ### Template
   
   The following code snippet provides a shell test program with two test cases:
   
     atf_test_case my_test_case      atf_test_case my_test_case
     my_test_case_head() {      my_test_case_head() {
         atf_set "descr" "This test case ensures that..."          atf_set "descr" "This test case ensures that..."
Line 189  For example: Line 252  For example:
         fi          fi
     }      }
   
       atf_test_case another_test_case
       another_test_case_body() {
           # Do more tests...
       }
   
     atf_init_test_cases() {      atf_init_test_cases() {
         atf_add_test_case my_test_case          atf_add_test_case my_test_case
           atf_add_test_case another_test_case
     }      }
   
   This program needs to be be executed with the atf-sh(1) interpreter as described
   below.  The program automatically gains an entry point that provides a
   consistent user interface to all test programs.  You are simply not inteded to
   provide your own "main method", nor to deal with the command-line of the
   invocation.
   
 ### How to build  ### How to build
   
 To build a shell test program, append the name of the test program (without the  To build a shell test program, append the name of the test program (without the

Removed from v.1.1  
changed lines
  Added in v.1.2


CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb