1TEST_UTIL(3) test_util 1.8 TEST_UTIL(3)
2
6 nfstest.test_util - Test utilities module
7
9 Provides a set of tools for testing either the NFS client or the NFS
10 server, most of the functionality is focused mainly on testing the
11 client. These tools include the following:
12 - Process command line arguments
14 - Provide functionality for PASS/FAIL
15 - Provide test grouping functionality
16 - Provide multiple client support
17 - Logging mechanism
18 - Debug info control
19 - Mount/Unmount control
20 - Create files/directories
21 - Provide mechanism to start a packet trace
22 - Provide mechanism to simulate a network partition
23 - Support for pNFS testing
24 In order to use some of the functionality available, the user id in all
26 the client hosts must have access to run commands as root using the
27 'sudo' command without the need for a password, this includes the host
28 where the test is being executed. This is used to run commands like
29 'mount' and 'umount'. Furthermore, the user id must be able to ssh to
30 remote hosts without the need for a password if test requires the use
31 of multiple clients.
32 Network partition is simulated by the use of 'iptables', please be ad‐
34 vised that after every test run the iptables is flushed and reset so
35 any rules previously setup will be lost. Currently, there is no mecha‐
36 nism to restore the iptables rules to their original state.
37
39 class TestUtil(nfstest.nfs_util.NFSUtil)
40 TestUtil object
41 TestUtil() -> New server object
43 Usage:
45 x = TestUtil()
46 # Process command line options
48 x.scan_options()
49 # Start packet trace using tcpdump
51 x.trace_start()
52 # Mount volume
54 x.mount()
55 # Create file
57 x.create_file()
58 # Unmount volume
60 x.umount()
61 # Stop packet trace
63 x.trace_stop()
64 # Exit script
66 x.exit()
67 Methods defined here:
70 ---------------------
71 __del__(self)
73 Destructor
74 Gracefully stop the packet trace, cleanup files, unmount volume,
76 and reset network.
77 __init__(self, **kwargs)
79 Constructor
80 Initialize object's private data.
82 sid: Test script ID [default: '']
85 This is used to have options targeted for a given ID without
86 including these options in any other test script.
87 usage: Usage string [default: '']
89 testnames:
91 List of test names [default: []]
92 When this list is not empty, the --runtest option is enabled and
93 test scripts should use the run_tests() method to run all the
94 tests. Test script should have methods named as <testname>_test.
95 testgroups:
97 Dictionary of test groups where the key is the name of the test
98 group and its value is a dictionary having the following keys:
99 tests:
100 A list of tests belonging to this test group
101 desc:
102 Description of the test group, this is displayed
103 in the help if the name of the test group is also
104 included in testnames
105 tincl:
106 Include a comma separated list of tests belonging to
107 this test group to the description [default: False]
108 wrap:
109 Reformat the description so it fits in lines no
110 more than the width given. The description is not
111 formatted for a value of zero [default: 72]
112 Example:
114 x = TestUtil(testnames=['basic', 'lock'])
115 # The following methods should exist:
117 x.basic_test()
118 x.lock_test()
119 cleanup(self)
121 Clean up test environment.
122 Remove any files created: test files, trace files.
124 close_files(self, *fdlist)
126 Close all files opened by open_files() and all file descriptors
127 given as arguments.
128 compare_data(self, data, offset=0, pattern=None, nlen=32, fd=None, msg='')
130 Compare data to the given pattern and return a three item tuple:
131 absolute offset where data differs from pattern, sample data at
132 diff offset, and the expected data at diff offset according to
133 pattern. If data matches exactly it returns (None, None, None).
134 data: Data to compare against the pattern
137 offset:
139 Absolute offset to get the expected data from pattern
140 [default: 0]
141 pattern:
143 Data pattern function or string. If this is a function,
144 it must take offset and size as positional arguments.
145 If given as a string, the pattern repeats over and over
146 starting at offset = 0 [default: self.data_pattern]
147 nlen: Size of sample data to return if a difference is found
149 [default: 32]
150 fd: Opened file descriptor for the data, this is used where
152 the data comes from a file and a difference is found right
153 at the end of the given data. In this case, the data is
154 read from the file to return the sample diff of size given
155 by nlen [default: None]
156 msg: Message to append to debug message if a difference is
158 found. If set to None, debug messages are not displayed
159 [default: '']
160 compare_mount_args(self, mtopts1, mtopts2)
162 Compare mount arguments
163 config(self, msg)
165 Display config message and terminate test with an exit value of 2.
166 create_dir(self, dir=None, mode=493)
168 Create a directory under the given directory with the given mode.
169 create_file(self, offset=0, size=None, dir=None, mode=None, **kwds)
171 Create a file starting to write at given offset with total size
172 of written data given by the size option.
173 offset:
176 File offset where data will be written to [default: 0]
177 size: Total number of bytes to write [default: --filesize option]
179 dir: Create file under this directory
181 mode: File permissions [default: use default OS permissions]
183 pattern:
185 Data pattern to write to the file [default: data_pattern default]
186 ftype: File type to create [default: FTYPE_FILE]
188 hole_list:
190 List of offsets where each hole is located [default: None]
191 hole_size:
193 Size of each hole [default: --wsize option]
194 verbose:
196 Verbosity level [default: 0]
197 dlevels:
199 Debug level list to use [default: ["DBG2", "DBG3", "DBG4"]]
200 Returns the file name created, the file name is also stored
202 in the object attribute filename -- attribute absfile is also
203 available as the absolute path of the file just created.
204 File created is removed at cleanup.
206 create_rexec(self, servername=None, **kwds)
208 Create remote server object.
209 data_pattern(self, offset, size, pattern=None)
211 Return data pattern.
212 offset:
215 Starting offset of pattern
216 size: Size of data to return
218 pattern:
220 Data pattern to return, default is of the form:
221 hex_offset(0x%08X) abcdefghijklmnopqrst
222 delay_io(self, delay=None)
224 Delay I/O by value given or the value given in --iodelay option.
225 exit(self)
227 Terminate script with an exit value of 0 when all tests passed
228 and a value of 1 when there is at least one test failure.
229 get_dirname(self, dir=None)
231 Return a unique directory name under the given directory.
232 get_filename(self, dir=None)
234 Return a unique file name under the given directory.
235 get_logname(self, remote=False)
237 Get next log file name.
238 get_marker_index(self, marker_id=None)
240 Find packet index of the trace marker given by the marker id
241 marker_id:
244 ID of trace marker to find in the packet trace, if this is
245 not given the current marker id is used [default: None]
246 get_name(self)
248 Get unique name for this instance.
249 insert_trace_marker(self, name=None)
251 Send a LOOKUP for an unknown file to have a marker in
252 the packet trace and return the trace marker id
253 name: Use this name as the trace marker but the caller must make
256 sure this is a unique name in order to find the correct
257 index for this marker. This could also be used to add any
258 arbitrary information to the packet trace [default: None]
259 lock_files(self, lock_type=None, offset=0, length=0)
261 Lock all files opened by open_files().
262 need_run_test(self, testname)
264 Return True only if user explicitly requested to run this test
265 open_files(self, mode, create=True)
267 Open files according to given mode, the file descriptors are saved
268 internally to be used with write_files(), read_files() and
269 close_files(). The number of files to open is controlled by
270 the command line option '--nfiles'.
271 The mode could be either 'r' or 'w' for opening files for reading
273 or writing respectively. The open flags for mode 'r' is O_RDONLY
274 while for mode 'w' is O_WRONLY|O_CREAT|O_SYNC. The O_SYNC is used
275 to avoid the client buffering the written data.
276 process_client_option(self, option='client', remote=True, count=1)
278 Process the client option
279 Clients are separated by a "," and each client definition can have
281 the following options separated by ":":
282 client:server:export:nfsversion:port:proto:sec:mtpoint
283 option:
286 Option name [default: "client"]
287 remote:
289 Expect a client hostname or IP address in the definition.
290 If this is set to None do not verify client name or IP.
291 [default: True]
292 count: Number of client definitions to expect. If remote is True,
294 return the number of definitions listed in the given option
295 up to this number. If remote is False, return exactly this
296 number of definitions [default: 1]
297 Examples:
299 # Using positional arguments with nfsversion=4.1 for client1
300 client=client1:::4.1,client2
301 # Using named arguments instead
303 client=client1:nfsversion=4.1,client2
304 process_option(self, value, arglist=[], typemap={})
306 Process option with a list of items separated by "," and each
307 item in the list could have different arguments separated by ":".
308 value: String of comma separated elements
311 arglist:
313 Positional order of arguments, if this list is empty,
314 then use named arguments only [default: []]
315 typemap:
317 Dictionary to convert arguments to their given types,
318 where the key is the argument name and its value is the
319 type function to use to convert the argument [default: {}]
320 read_files(self)
322 Read a block of data (size given by --rsize) from all files opened
323 by open_files() for reading.
324 remove_test(self, testname)
326 Remove all instances of test from the list of tests to run
327 run_func(self, func, *args, **kwargs)
329 Run function with the given arguments and return the results.
330 All positional arguments are passed to the function while the
331 named arguments change the behavior of the method.
332 Object attribute "oserror" is set to the OSError object if the
333 function fails.
334 msg: Test assertion message [default: None]
337 err: Expected error number [default: 0]
339 run_tests(self, **kwargs)
341 Run all test specified by the --runtest option.
342 testnames:
345 List of testnames to run [default: all tests given by --testnames]
346 All other arguments given are passed to the test methods.
348 scan_options(self)
350 Process command line options.
351 Process all the options in the file given by '--file', then the
353 ones in the command line. This allows for command line options
354 to over write options given in the file.
355 Format of options file:
357 # For options expecting a value
358 <option_name> = <value>
359 # For boolean (flag) options
361 <option_name>
362 Process options files and make sure not to process the same file
364 twice, this is used for the case where HOMECFG and CWDCFG are the
365 same, more specifically when environment variable HOME is not
366 defined. Also, the precedence order is defined as follows:
367 1. options given in command line
368 2. options given in file specified by the -f|--file option
369 3. options given in file specified by ./.nfstest
370 4. options given in file specified by $HOME/.nfstest
371 5. options given in file specified by /etc/nfstest
372 NOTE:
374 Must use the long name of the option (--<option_name>) in the file.
375 set_nfserr_list(self, nfs3list=[], nfs4list=[], nlm4list=[], mnt3list=[])
377 Temporaly set the NFS list of expected NFS errors in the next call
378 to trace_open
379 setup(self, nfiles=None)
381 Set up test environment.
382 Create nfiles number of files [default: --nfiles option]
384 str_args(self, args)
386 Return the formal string representation of the given list
387 where string objects are truncated.
388 test(self, expr, msg, subtest=None, failmsg=None, terminate=False)
390 Test expr and display message as PASS/FAIL, terminate execution
391 if terminate option is True.
392 expr: If expr is true, display as a PASS message,
395 otherwise as a FAIL message
396 msg: Message to display
398 subtest:
400 If given, append this string to the displayed message and
401 mark this test as a member of the sub-group given by msg
402 failmsg:
404 If given, append this string to the displayed message when
405 expr is false [default: None]
406 terminate:
408 Terminate execution if true and expr is false [default: False]
409 If tverbose=normal or level 1:
411 Sub-group message is displayed as a PASS/FAIL message including
412 the number of tests that passed and failed within the sub-group
413 If tverbose=verbose or level 2:
414 All tests messages are displayed
415 test_description(self, tname=None)
417 Return the test description for the current test
418 test_group(self, msg)
420 Display heading message and start a test group.
421 If tverbose=group or level 0:
423 Group message is displayed as a PASS/FAIL message including the
424 number of tests that passed and failed within this test group.
425 If tverbose=normal|verbose or level 1|2:
426 Group message is displayed as a heading messages for the tests
427 belonging to this test group.
428 test_info(self, msg)
430 Display info message.
431 test_options(self, name=None)
433 Get options for the given test name. If the test name is not given
434 it is determined by inspecting the stack to find which method is
435 calling this method.
436 testid_count(self, tid)
438 Return the number of instances the testid has occurred.
439 trace_open(self, *kwts, **kwds)
441 This is a wrapper to the original trace_open method where the
442 packet trace is scanned for NFS errors and a failure is logged
443 for each error found not given on the list of expected errors
444 set with method set_nfserr_list. Scanning for NFS error is done
445 only if --nfserrors option has been specified.
446 trace_start(self, *kwts, **kwds)
448 This is a wrapper to the original trace_start method to reset
449 the trace marker state
450 verify_client_option(self, tclient_dict, option='client')
452 Verify the client option is required from the list of tests to run.
453 Also, check if enough clients were specified to run the tests.
454 tclient_dict:
457 Dictionary having the number of clients required by each test
458 option:
460 Option name [default: "client"]
461 verify_file_data(self, msg=None, pattern=None, path=None, filesize=None, nlen=None, cmsg='')
463 Verify file by comparing the data to the given pattern.
464 It returns the results from the compare_data method.
465 msg: Test assertion message. If set to None, no assertion is
468 done it just returns the results [default: None]
469 pattern:
471 Data pattern function or string. If this is a function,
472 it must take offset and size as positional arguments.
473 If given as a string, the pattern repeats over and over
474 starting at offset = 0 [default: self.data_pattern]
475 path: Absolute path of file to verify [default: self.absfile]
477 filesize:
479 Expected size of file to be verified [default: self.filesize]
480 nlen: Size of sample data to return if a difference is found
482 [default: compare_data default]
483 cmsg: Message to append to debug message if a difference is
485 found. If set to None, debug messages are not displayed
486 [default: '']
487 warning(self, msg)
489 Display warning message.
490 write_data(self, fd, offset=0, size=None, pattern=None, verbose=0, dlevel='DBG5')
492 Write data to the file given by the file descriptor
493 fd: File descriptor
496 offset:
498 File offset where data will be written to [default: 0]
499 size: Total number of bytes to write [default: --filesize option]
501 pattern:
503 Data pattern to write to the file [default: data_pattern default]
504 verbose:
506 Verbosity level [default: 0]
507 write_files(self)
509 Write a block of data (size given by --wsize) to all files opened
510 by open_files() for writing.
511 Static methods defined here:
513 ----------------------------
514 get_list(value, nmap, sep=',')
516 Given the value as a string of 'comma' separated elements, return
517 a list where each element is mapped using the dictionary 'nmap'.
518 nmap = {"one":1, "two":2}
519 out = x.get_list("one", nmap) # out = [1]
520 out = x.get_list("one,two", nmap) # out = [1,2]
521 out = x.get_list("two,one", nmap) # out = [2,1]
522 out = x.get_list("one,three", nmap) # out = None
523 str_list(value, vtype=<class 'str'>, sep=',')
525 Return a list of <vtype> elements from the comma separated string.
526
528 baseobj(3), formatstr(3), nfstest.host(3), nfstest.nfs_util(3), nf‐
529 stest.rexec(3), nfstest.utils(3), packet.nfs.nfs3_const(3),
530 packet.nfs.nfs4_const(3)
531
534 No known bugs.
535
537 Jorge Mora (mora@netapp.com)
538NFStest 3.2 21 March 2023 TEST_UTIL(3)