| 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 -- To unsubscribe from this list: send the line "unsubscribe fstests" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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 -- To unsubscribe from this list: send the line "unsubscribe fstests" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
| 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 -- To unsubscribe from this list: send the line "unsubscribe fstests" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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 -- To unsubscribe from this list: send the line "unsubscribe fstests" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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 -- To unsubscribe from this list: send the line "unsubscribe fstests" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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 -- To unsubscribe from this list: send the line "unsubscribe fstests" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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.