| Message ID | 149132132595.18980.156040870381065105.stgit@warthog.procyon.org.uk (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Tue, Apr 04, 2017 at 04:55:25PM +0100, David Howells wrote: > Partially expand the documentation available in xfstests to include > requirements checking and auxiliary programs for testing. > > Signed-off-by: David Howells <dhowells@redhat.com> > Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com> > --- > > doc/auxiliary-programs.txt | 56 ++++++++++++++++++++++++++++++++++ > doc/requirement-checking.txt | 69 ++++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 125 insertions(+) > create mode 100644 doc/auxiliary-programs.txt > create mode 100644 doc/requirement-checking.txt > > diff --git a/doc/auxiliary-programs.txt b/doc/auxiliary-programs.txt > new file mode 100644 > index 0000000..17797b0 > --- /dev/null > +++ b/doc/auxiliary-programs.txt > @@ -0,0 +1,56 @@ > + ============================== > + AUXILIARY PROGRAMS FOR TESTING > + ============================== > + > +Not everything a test script can do is easily done within a test script; > +sometimes it makes a lot more sense to write auxiliary program in C and have > +the test script call them. Auxiliary commands can be found in the src/ > +directory and in other packages. > + > +Tests wanting to use an auxiliary program found in the src/ directory should > +note the dependency with: > + > + _require_test_program "<program-name>" > + > + > +Contents: > + > + - af_unix -- Create an AF_UNIX socket > + - stat_test -- statx syscall exercise > + - xfs_io -- General I/O operation exercise > + > + > +================== > +QUICK DESCRIPTIONS > +================== > + > +af_unix > + > + The af_unix program creates an AF_UNIX socket at the given location. > + > +stat_test > + > + The stat_test program is primarily designed to exercise the statx() > + system call. It can check statx() against fstatat() and it can > + compare and check various file attributes. > + > + See also: > + _require_statx > + > + > +xfs_io > + > + The xfs_io program can be found in the xfsprogs package and can be used > + to perform sequences of I/O commands, though it is limited to what it > + can do on open files. > + > + xfs_io is a debugging tool that is aimed at examining regular file I/O > + paths rather than a raw XFS volume itself. These code paths include > + not only the obvious read/write/mmap interfaces for manipulating files, > + but also cover all of the XFS extensions (such as space preallocation, > + additional inode flags, etc). > + > + Most of its commands can also be used with other filesystems. > + > + See also: > + _require_xfs_io_command > diff --git a/doc/requirement-checking.txt b/doc/requirement-checking.txt > new file mode 100644 > index 0000000..29f0b74 > --- /dev/null > +++ b/doc/requirement-checking.txt > @@ -0,0 +1,69 @@ > + ======================================== > + TESTING FOR REQUIREMENTS IN TEST SCRIPTS > + ======================================== > + > +Test scripts need to indicate to the infrastructure what sorts of requirements > +they have. This is done with _require_<xxx> macros, which may take parameters. > + > + (1) General requirements. > + > + _require_command > + _require_test > + _require_test_program > + _require_xfs_io_command > + > + (2) System call requirements. > + > + _require_statx > + > + > +==================== > +GENERAL REQUIREMENTS > +==================== > + > +_require_command "$VAR" name > + > + The test requires an external command, called 'name' be present on the > + system and that '$VAR' should be set with the path to that command. $VAR > + should then be used to refer to the command when executing it. For > + example: > + > + _require_command "$NC_PROG" "nc" > + > + to locate the netcat command and then: > + > + $NC_PROG -U -l $TEST_DIR/$seq-sock Hmm, NC_PROG is not defined/used anymore, perhaps it's not a good example for document purpose. How about $KILLALL_PROG? It's often forgotten and it could be a reminder in doc. Thanks, Eryu
Eryu Guan <eguan@redhat.com> wrote: > Hmm, NC_PROG is not defined/used anymore, perhaps it's not a good > example for document purpose. How about $KILLALL_PROG? It's often > forgotten and it could be a reminder in doc. I'll switch to that. David
| 388:45: $KILLALL_PROG -9 fsstress > /dev/null 2>&1 | 388:58:_require_command "$KILLALL_PROG" "killall" | 388:79: $KILLALL_PROG -9 fsstress > /dev/null 2>&1 Should this be using _require_command for fsstress and $FSSTRESS_PROG like the other tests that use fsstress? Also, should 388 be printing "Silence is golden" at the end of the test? David
On Wed, Apr 05, 2017 at 11:59:15AM +0100, David Howells wrote: > | 388:45: $KILLALL_PROG -9 fsstress > /dev/null 2>&1 > | 388:58:_require_command "$KILLALL_PROG" "killall" > | 388:79: $KILLALL_PROG -9 fsstress > /dev/null 2>&1 > > Should this be using _require_command for fsstress and $FSSTRESS_PROG like the > other tests that use fsstress? fsstress is a bit special, it's mandatory for xfstests, it's checked in common/config [ ! -x $FSSTRESS_PROG ] && _fatal "fsstress not found or executable" (Perhaps we should treat fsstress just as other test binaries, but it's been this way since the beginning of xfstests.) And generic/388 does invoke fsstress by calling $FSSTRESS_PROG, but not necessary in this killall case. We define NAME_PROG variables mainly for doing tweeks easily in this variable, like adding an option globally. Take $XFS_IO_PROG as an example in init_rc. # Figure out if we need to add -F ("foreign", deprecated) option to xfs_io $XFS_IO_PROG -c stat $TEST_DIR 2>&1 | grep -q "is not on an XFS filesystem" && \ export XFS_IO_PROG="$XFS_IO_PROG -F" > > Also, should 388 be printing "Silence is golden" at the end of the test? Yes, and it does print this message, but in the middle of test, not end. Thanks, Eryu
Eryu Guan <eguan@redhat.com> wrote: > > Also, should 388 be printing "Silence is golden" at the end of the test? > > Yes, and it does print this message, but in the middle of test, not end. Yes. I know it prints the message but not at the end. Why the middle and not the end is the question? David
On Wed, Apr 05, 2017 at 12:17:17PM +0100, David Howells wrote: > Eryu Guan <eguan@redhat.com> wrote: > > > > Also, should 388 be printing "Silence is golden" at the end of the test? > > > > Yes, and it does print this message, but in the middle of test, not end. > > Yes. I know it prints the message but not at the end. Why the middle and not > the end is the question? Oh, OK, it doesn't really matter, many tests print it just after setting test up, as long as it prints it. Thanks, Eryu
diff --git a/doc/auxiliary-programs.txt b/doc/auxiliary-programs.txt new file mode 100644 index 0000000..17797b0 --- /dev/null +++ b/doc/auxiliary-programs.txt @@ -0,0 +1,56 @@ + ============================== + AUXILIARY PROGRAMS FOR TESTING + ============================== + +Not everything a test script can do is easily done within a test script; +sometimes it makes a lot more sense to write auxiliary program in C and have +the test script call them. Auxiliary commands can be found in the src/ +directory and in other packages. + +Tests wanting to use an auxiliary program found in the src/ directory should +note the dependency with: + + _require_test_program "<program-name>" + + +Contents: + + - af_unix -- Create an AF_UNIX socket + - stat_test -- statx syscall exercise + - xfs_io -- General I/O operation exercise + + +================== +QUICK DESCRIPTIONS +================== + +af_unix + + The af_unix program creates an AF_UNIX socket at the given location. + +stat_test + + The stat_test program is primarily designed to exercise the statx() + system call. It can check statx() against fstatat() and it can + compare and check various file attributes. + + See also: + _require_statx + + +xfs_io + + The xfs_io program can be found in the xfsprogs package and can be used + to perform sequences of I/O commands, though it is limited to what it + can do on open files. + + xfs_io is a debugging tool that is aimed at examining regular file I/O + paths rather than a raw XFS volume itself. These code paths include + not only the obvious read/write/mmap interfaces for manipulating files, + but also cover all of the XFS extensions (such as space preallocation, + additional inode flags, etc). + + Most of its commands can also be used with other filesystems. + + See also: + _require_xfs_io_command diff --git a/doc/requirement-checking.txt b/doc/requirement-checking.txt new file mode 100644 index 0000000..29f0b74 --- /dev/null +++ b/doc/requirement-checking.txt @@ -0,0 +1,69 @@ + ======================================== + TESTING FOR REQUIREMENTS IN TEST SCRIPTS + ======================================== + +Test scripts need to indicate to the infrastructure what sorts of requirements +they have. This is done with _require_<xxx> macros, which may take parameters. + + (1) General requirements. + + _require_command + _require_test + _require_test_program + _require_xfs_io_command + + (2) System call requirements. + + _require_statx + + +==================== +GENERAL REQUIREMENTS +==================== + +_require_command "$VAR" name + + The test requires an external command, called 'name' be present on the + system and that '$VAR' should be set with the path to that command. $VAR + should then be used to refer to the command when executing it. For + example: + + _require_command "$NC_PROG" "nc" + + to locate the netcat command and then: + + $NC_PROG -U -l $TEST_DIR/$seq-sock + + to make use of it. + + +_require_test + + The test requires that the block device specified by $TEST_DEV be mounted + on $TEST_DIR. + + +_require_test_program "name" + + The test requires a program by the name of 'name' be present and built in + the src/ directory. For example: + + _require_test_program "stat_test" + + requires that src/stat_test be built. + + +_require_xfs_io_command "falloc" + + The test requires that the xfs_io command be available and that it support + the 'falloc' command. + + +======================== +SYSTEM CALL REQUIREMENTS +======================== + +_require_statx + + The test requires the use of the statx() system call and will be skipped + if it isn't available in the kernel.