2 # SPDX-License-Identifier: GPL-2.0-only
4 # Copyright (c) 2019 Western Digital Corporation or its affiliates.
9 # Automate running of fio tests
12 # python3 run-fio-tests.py [-r fio-root] [-f fio-path] [-a artifact-root]
13 # [--skip # # #...] [--run-only # # #...]
17 # # git clone git://git.kernel.dk/fio.git
20 # # python3 t/run-fio-tests.py
24 # - Python 3.5 (subprocess.run)
25 # - Linux (libaio ioengine, zbd tests, etc)
26 # - The artifact directory must be on a file system that accepts 512-byte IO
27 # (t0002, t0003, t0004).
28 # - The artifact directory needs to be on an SSD. Otherwise tests that carry
29 # out file-based IO will trigger a timeout (t0006).
31 # - SciPy (steadystate_tests.py)
32 # - libzbc (zbd tests)
33 # - root privileges (zbd test)
34 # - kernel 4.19 or later for zoned null block devices (zbd tests)
35 # - CUnit support (unittests)
40 # TODO run multiple tests simultaneously
41 # TODO Add sgunmap tests (requires SAS SSD)
53 import multiprocessing
54 from pathlib import Path
57 class FioTest(object):
58 """Base for all fio tests."""
60 def __init__(self, exe_path, parameters, success):
61 self.exe_path = exe_path
62 self.parameters = parameters
63 self.success = success
65 self.artifact_root = None
69 self.failure_reason = ''
70 self.command_file = None
71 self.stdout_file = None
72 self.stderr_file = None
73 self.exitcode_file = None
75 def setup(self, artifact_root, testnum):
76 """Setup instance variables for test."""
78 self.artifact_root = artifact_root
79 self.testnum = testnum
80 self.test_dir = os.path.join(artifact_root, "{:04d}".format(testnum))
81 if not os.path.exists(self.test_dir):
82 os.mkdir(self.test_dir)
84 self.command_file = os.path.join(
86 "{0}.command".format(os.path.basename(self.exe_path)))
87 self.stdout_file = os.path.join(
89 "{0}.stdout".format(os.path.basename(self.exe_path)))
90 self.stderr_file = os.path.join(
92 "{0}.stderr".format(os.path.basename(self.exe_path)))
93 self.exitcode_file = os.path.join(
95 "{0}.exitcode".format(os.path.basename(self.exe_path)))
100 raise NotImplementedError()
102 def check_result(self):
103 """Check test results."""
105 raise NotImplementedError()
108 class FioExeTest(FioTest):
109 """Test consists of an executable binary or script"""
111 def __init__(self, exe_path, parameters, success):
112 """Construct a FioExeTest which is a FioTest consisting of an
113 executable binary or script.
115 exe_path: location of executable binary or script
116 parameters: list of parameters for executable
117 success: Definition of test success
120 FioTest.__init__(self, exe_path, parameters, success)
123 """Execute the binary or script described by this instance."""
125 command = [self.exe_path] + self.parameters
126 command_file = open(self.command_file, "w+")
127 command_file.write("%s\n" % command)
130 stdout_file = open(self.stdout_file, "w+")
131 stderr_file = open(self.stderr_file, "w+")
132 exitcode_file = open(self.exitcode_file, "w+")
135 # Avoid using subprocess.run() here because when a timeout occurs,
136 # fio will be stopped with SIGKILL. This does not give fio a
137 # chance to clean up and means that child processes may continue
138 # running and submitting IO.
139 proc = subprocess.Popen(command,
143 universal_newlines=True)
144 proc.communicate(timeout=self.success['timeout'])
145 exitcode_file.write('{0}\n'.format(proc.returncode))
146 logging.debug("Test %d: return code: %d", self.testnum, proc.returncode)
147 self.output['proc'] = proc
148 except subprocess.TimeoutExpired:
152 self.output['failure'] = 'timeout'
158 self.output['failure'] = 'exception'
159 self.output['exc_info'] = sys.exc_info()
163 exitcode_file.close()
165 def check_result(self):
166 """Check results of test run."""
168 if 'proc' not in self.output:
169 if self.output['failure'] == 'timeout':
170 self.failure_reason = "{0} timeout,".format(self.failure_reason)
172 assert self.output['failure'] == 'exception'
173 self.failure_reason = '{0} exception: {1}, {2}'.format(
174 self.failure_reason, self.output['exc_info'][0],
175 self.output['exc_info'][1])
180 if 'zero_return' in self.success:
181 if self.success['zero_return']:
182 if self.output['proc'].returncode != 0:
184 self.failure_reason = "{0} non-zero return code,".format(self.failure_reason)
186 if self.output['proc'].returncode == 0:
187 self.failure_reason = "{0} zero return code,".format(self.failure_reason)
190 stderr_size = os.path.getsize(self.stderr_file)
191 if 'stderr_empty' in self.success:
192 if self.success['stderr_empty']:
194 self.failure_reason = "{0} stderr not empty,".format(self.failure_reason)
198 self.failure_reason = "{0} stderr empty,".format(self.failure_reason)
202 class FioJobTest(FioExeTest):
203 """Test consists of a fio job"""
205 def __init__(self, fio_path, fio_job, success, fio_pre_job=None,
206 fio_pre_success=None, output_format="normal"):
207 """Construct a FioJobTest which is a FioExeTest consisting of a
208 single fio job file with an optional setup step.
210 fio_path: location of fio executable
211 fio_job: location of fio job file
212 success: Definition of test success
213 fio_pre_job: fio job for preconditioning
214 fio_pre_success: Definition of test success for fio precon job
215 output_format: normal (default), json, jsonplus, or terse
218 self.fio_job = fio_job
219 self.fio_pre_job = fio_pre_job
220 self.fio_pre_success = fio_pre_success if fio_pre_success else success
221 self.output_format = output_format
222 self.precon_failed = False
223 self.json_data = None
224 self.fio_output = "{0}.output".format(os.path.basename(self.fio_job))
227 "--output-format={0}".format(self.output_format),
228 "--output={0}".format(self.fio_output),
231 FioExeTest.__init__(self, fio_path, self.fio_args, success)
233 def setup(self, artifact_root, testnum):
234 """Setup instance variables for fio job test."""
236 super(FioJobTest, self).setup(artifact_root, testnum)
238 self.command_file = os.path.join(
240 "{0}.command".format(os.path.basename(self.fio_job)))
241 self.stdout_file = os.path.join(
243 "{0}.stdout".format(os.path.basename(self.fio_job)))
244 self.stderr_file = os.path.join(
246 "{0}.stderr".format(os.path.basename(self.fio_job)))
247 self.exitcode_file = os.path.join(
249 "{0}.exitcode".format(os.path.basename(self.fio_job)))
251 def run_pre_job(self):
252 """Run fio job precondition step."""
254 precon = FioJobTest(self.exe_path, self.fio_pre_job,
255 self.fio_pre_success,
256 output_format=self.output_format)
257 precon.setup(self.artifact_root, self.testnum)
259 precon.check_result()
260 self.precon_failed = not precon.passed
261 self.failure_reason = precon.failure_reason
264 """Run fio job test."""
269 if not self.precon_failed:
270 super(FioJobTest, self).run()
272 logging.debug("Test %d: precondition step failed", self.testnum)
275 def get_file(cls, filename):
276 """Safely read a file."""
281 with open(filename, "r") as output_file:
282 file_data = output_file.read()
286 return file_data, success
288 def check_result(self):
289 """Check fio job results."""
291 if self.precon_failed:
293 self.failure_reason = "{0} precondition step failed,".format(self.failure_reason)
296 super(FioJobTest, self).check_result()
301 if 'json' not in self.output_format:
304 file_data, success = self.get_file(os.path.join(self.test_dir, self.fio_output))
306 self.failure_reason = "{0} unable to open output file,".format(self.failure_reason)
311 # Sometimes fio informational messages are included at the top of the
312 # JSON output, especially under Windows. Try to decode output as JSON
313 # data, lopping off up to the first four lines
315 lines = file_data.splitlines()
317 file_data = '\n'.join(lines[i:])
319 self.json_data = json.loads(file_data)
320 except json.JSONDecodeError:
323 logging.debug("Test %d: skipped %d lines decoding JSON data", self.testnum, i)
326 self.failure_reason = "{0} unable to decode JSON data,".format(self.failure_reason)
330 class FioJobTest_t0005(FioJobTest):
331 """Test consists of fio test job t0005
332 Confirm that read['io_kbytes'] == write['io_kbytes'] == 102400"""
334 def check_result(self):
335 super(FioJobTest_t0005, self).check_result()
340 if self.json_data['jobs'][0]['read']['io_kbytes'] != 102400:
341 self.failure_reason = "{0} bytes read mismatch,".format(self.failure_reason)
343 if self.json_data['jobs'][0]['write']['io_kbytes'] != 102400:
344 self.failure_reason = "{0} bytes written mismatch,".format(self.failure_reason)
348 class FioJobTest_t0006(FioJobTest):
349 """Test consists of fio test job t0006
350 Confirm that read['io_kbytes'] ~ 2*write['io_kbytes']"""
352 def check_result(self):
353 super(FioJobTest_t0006, self).check_result()
358 ratio = self.json_data['jobs'][0]['read']['io_kbytes'] \
359 / self.json_data['jobs'][0]['write']['io_kbytes']
360 logging.debug("Test %d: ratio: %f", self.testnum, ratio)
361 if ratio < 1.99 or ratio > 2.01:
362 self.failure_reason = "{0} read/write ratio mismatch,".format(self.failure_reason)
366 class FioJobTest_t0007(FioJobTest):
367 """Test consists of fio test job t0007
368 Confirm that read['io_kbytes'] = 87040"""
370 def check_result(self):
371 super(FioJobTest_t0007, self).check_result()
376 if self.json_data['jobs'][0]['read']['io_kbytes'] != 87040:
377 self.failure_reason = "{0} bytes read mismatch,".format(self.failure_reason)
381 class FioJobTest_t0008(FioJobTest):
382 """Test consists of fio test job t0008
383 Confirm that read['io_kbytes'] = 32768 and that
384 write['io_kbytes'] ~ 16568
386 I did runs with fio-ae2fafc8 and saw write['io_kbytes'] values of
387 16585, 16588. With two runs of fio-3.16 I obtained 16568"""
389 def check_result(self):
390 super(FioJobTest_t0008, self).check_result()
395 ratio = self.json_data['jobs'][0]['write']['io_kbytes'] / 16568
396 logging.debug("Test %d: ratio: %f", self.testnum, ratio)
398 if ratio < 0.99 or ratio > 1.01:
399 self.failure_reason = "{0} bytes written mismatch,".format(self.failure_reason)
401 if self.json_data['jobs'][0]['read']['io_kbytes'] != 32768:
402 self.failure_reason = "{0} bytes read mismatch,".format(self.failure_reason)
406 class FioJobTest_t0009(FioJobTest):
407 """Test consists of fio test job t0009
408 Confirm that runtime >= 60s"""
410 def check_result(self):
411 super(FioJobTest_t0009, self).check_result()
416 logging.debug('Test %d: elapsed: %d', self.testnum, self.json_data['jobs'][0]['elapsed'])
418 if self.json_data['jobs'][0]['elapsed'] < 60:
419 self.failure_reason = "{0} elapsed time mismatch,".format(self.failure_reason)
423 class FioJobTest_iops_rate(FioJobTest):
424 """Test consists of fio test job t0009
425 Confirm that job0 iops == 1000
426 and that job1_iops / job0_iops ~ 8
427 With two runs of fio-3.16 I observed a ratio of 8.3"""
429 def check_result(self):
430 super(FioJobTest_iops_rate, self).check_result()
435 iops1 = self.json_data['jobs'][0]['read']['iops']
436 iops2 = self.json_data['jobs'][1]['read']['iops']
437 ratio = iops2 / iops1
438 logging.debug("Test %d: iops1: %f", self.testnum, iops1)
439 logging.debug("Test %d: ratio: %f", self.testnum, ratio)
441 if iops1 < 950 or iops1 > 1050:
442 self.failure_reason = "{0} iops value mismatch,".format(self.failure_reason)
445 if ratio < 7 or ratio > 9:
446 self.failure_reason = "{0} iops ratio mismatch,".format(self.failure_reason)
450 class FioJobTest_t0013(FioJobTest):
451 """Runs fio test job t0013"""
453 def check_result(self):
454 super(FioJobTest_t0013, self).check_result()
457 class Requirements(object):
458 """Requirements consists of multiple run environment characteristics.
459 These are to determine if a particular test can be run"""
471 def __init__(self, fio_root):
472 Requirements._not_macos = platform.system() != "Darwin"
473 Requirements._not_windows = platform.system() != "Windows"
474 Requirements._linux = platform.system() == "Linux"
476 if Requirements._linux:
477 config_file = os.path.join(fio_root, "config-host.h")
478 contents, success = FioJobTest.get_file(config_file)
480 print("Unable to open {0} to check requirements".format(config_file))
481 Requirements._zbd = True
483 Requirements._zbd = "CONFIG_HAS_BLKZONED" in contents
484 Requirements._libaio = "CONFIG_LIBAIO" in contents
486 Requirements._root = (os.geteuid() == 0)
487 if Requirements._zbd and Requirements._root:
488 subprocess.run(["modprobe", "null_blk"],
489 stdout=subprocess.PIPE,
490 stderr=subprocess.PIPE)
491 if os.path.exists("/sys/module/null_blk/parameters/zoned"):
492 Requirements._zoned_nullb = True
494 if platform.system() == "Windows":
495 utest_exe = "unittest.exe"
497 utest_exe = "unittest"
498 unittest_path = os.path.join(fio_root, "unittests", utest_exe)
499 Requirements._unittests = os.path.exists(unittest_path)
501 Requirements._cpucount4 = multiprocessing.cpu_count() >= 4
503 req_list = [Requirements.linux,
507 Requirements.zoned_nullb,
508 Requirements.not_macos,
509 Requirements.not_windows,
510 Requirements.unittests,
511 Requirements.cpucount4]
514 logging.debug("Requirements: Requirement '%s' met? %s", desc, value)
518 """Are we running on Linux?"""
519 return Requirements._linux, "Linux required"
523 """Is libaio available?"""
524 return Requirements._libaio, "libaio required"
528 """Is ZBD support available?"""
529 return Requirements._zbd, "Zoned block device support required"
533 """Are we running as root?"""
534 return Requirements._root, "root required"
537 def zoned_nullb(cls):
538 """Are zoned null block devices available?"""
539 return Requirements._zoned_nullb, "Zoned null block device support required"
543 """Are we running on a platform other than macOS?"""
544 return Requirements._not_macos, "platform other than macOS required"
547 def not_windows(cls):
548 """Are we running on a platform other than Windws?"""
549 return Requirements._not_windows, "platform other than Windows required"
553 """Were unittests built?"""
554 return Requirements._unittests, "Unittests support required"
558 """Do we have at least 4 CPUs?"""
559 return Requirements._cpucount4, "4+ CPUs required"
564 'stderr_empty': True,
568 'zero_return': False,
569 'stderr_empty': False,
574 'stderr_empty': False,
580 'test_class': FioJobTest,
581 'job': 't0001-52c58027.fio',
582 'success': SUCCESS_DEFAULT,
589 'test_class': FioJobTest,
590 'job': 't0002-13af05ae-post.fio',
591 'success': SUCCESS_DEFAULT,
592 'pre_job': 't0002-13af05ae-pre.fio',
594 'requirements': [Requirements.linux, Requirements.libaio],
598 'test_class': FioJobTest,
599 'job': 't0003-0ae2c6e1-post.fio',
600 'success': SUCCESS_NONZERO,
601 'pre_job': 't0003-0ae2c6e1-pre.fio',
602 'pre_success': SUCCESS_DEFAULT,
603 'requirements': [Requirements.linux, Requirements.libaio],
607 'test_class': FioJobTest,
608 'job': 't0004-8a99fdf6.fio',
609 'success': SUCCESS_DEFAULT,
612 'requirements': [Requirements.linux, Requirements.libaio],
616 'test_class': FioJobTest_t0005,
617 'job': 't0005-f7078f7b.fio',
618 'success': SUCCESS_DEFAULT,
621 'output_format': 'json',
622 'requirements': [Requirements.not_windows],
626 'test_class': FioJobTest_t0006,
627 'job': 't0006-82af2a7c.fio',
628 'success': SUCCESS_DEFAULT,
631 'output_format': 'json',
632 'requirements': [Requirements.linux, Requirements.libaio],
636 'test_class': FioJobTest_t0007,
637 'job': 't0007-37cf9e3c.fio',
638 'success': SUCCESS_DEFAULT,
641 'output_format': 'json',
646 'test_class': FioJobTest_t0008,
647 'job': 't0008-ae2fafc8.fio',
648 'success': SUCCESS_DEFAULT,
651 'output_format': 'json',
656 'test_class': FioJobTest_t0009,
657 'job': 't0009-f8b0bd10.fio',
658 'success': SUCCESS_DEFAULT,
661 'output_format': 'json',
662 'requirements': [Requirements.not_macos,
663 Requirements.cpucount4],
664 # mac os does not support CPU affinity
668 'test_class': FioJobTest,
669 'job': 't0010-b7aae4ba.fio',
670 'success': SUCCESS_DEFAULT,
677 'test_class': FioJobTest_iops_rate,
678 'job': 't0011-5d2788d5.fio',
679 'success': SUCCESS_DEFAULT,
682 'output_format': 'json',
687 'test_class': FioJobTest_iops_rate,
689 'success': SUCCESS_DEFAULT,
692 'output_format': 'json',
694 'requirements': [Requirements.not_macos],
695 # mac os does not support CPU affinity
699 'test_class': FioJobTest_t0013,
701 'success': SUCCESS_DEFAULT,
704 'output_format': 'json',
709 'test_class': FioExeTest,
712 'success': SUCCESS_DEFAULT,
717 'test_class': FioExeTest,
720 'success': SUCCESS_DEFAULT,
725 'test_class': FioExeTest,
726 'exe': 't/lfsr-test',
727 'parameters': ['0xFFFFFF', '0', '0', 'verify'],
728 'success': SUCCESS_STDERR,
733 'test_class': FioExeTest,
734 'exe': 't/readonly.py',
735 'parameters': ['-f', '{fio_path}'],
736 'success': SUCCESS_DEFAULT,
741 'test_class': FioExeTest,
742 'exe': 't/steadystate_tests.py',
743 'parameters': ['{fio_path}'],
744 'success': SUCCESS_DEFAULT,
749 'test_class': FioExeTest,
752 'success': SUCCESS_STDERR,
757 'test_class': FioExeTest,
758 'exe': 't/strided.py',
759 'parameters': ['{fio_path}'],
760 'success': SUCCESS_DEFAULT,
765 'test_class': FioExeTest,
766 'exe': 't/zbd/run-tests-against-regular-nullb',
768 'success': SUCCESS_DEFAULT,
769 'requirements': [Requirements.linux, Requirements.zbd,
774 'test_class': FioExeTest,
775 'exe': 't/zbd/run-tests-against-zoned-nullb',
777 'success': SUCCESS_DEFAULT,
778 'requirements': [Requirements.linux, Requirements.zbd,
779 Requirements.root, Requirements.zoned_nullb],
783 'test_class': FioExeTest,
784 'exe': 'unittests/unittest',
786 'success': SUCCESS_DEFAULT,
787 'requirements': [Requirements.unittests],
791 'test_class': FioExeTest,
792 'exe': 't/latency_percentiles.py',
793 'parameters': ['-f', '{fio_path}'],
794 'success': SUCCESS_DEFAULT,
799 'test_class': FioExeTest,
800 'exe': 't/jsonplus2csv_test.py',
801 'parameters': ['-f', '{fio_path}'],
802 'success': SUCCESS_DEFAULT,
809 """Parse command-line arguments."""
811 parser = argparse.ArgumentParser()
812 parser.add_argument('-r', '--fio-root',
813 help='fio root path')
814 parser.add_argument('-f', '--fio',
815 help='path to fio executable (e.g., ./fio)')
816 parser.add_argument('-a', '--artifact-root',
817 help='artifact root directory')
818 parser.add_argument('-s', '--skip', nargs='+', type=int,
819 help='list of test(s) to skip')
820 parser.add_argument('-o', '--run-only', nargs='+', type=int,
821 help='list of test(s) to run, skipping all others')
822 parser.add_argument('-d', '--debug', action='store_true',
823 help='provide debug output')
824 parser.add_argument('-k', '--skip-req', action='store_true',
825 help='skip requirements checking')
826 parser.add_argument('-p', '--pass-through', action='append',
827 help='pass-through an argument to an executable test')
828 args = parser.parse_args()
838 logging.basicConfig(level=logging.DEBUG)
840 logging.basicConfig(level=logging.INFO)
843 if args.pass_through:
844 for arg in args.pass_through:
846 print("Invalid --pass-through argument '%s'" % arg)
847 print("Syntax for --pass-through is TESTNUMBER:ARGUMENT")
849 split = arg.split(":",1)
850 pass_through[int(split[0])] = split[1]
851 logging.debug("Pass-through arguments: %s" % pass_through)
854 fio_root = args.fio_root
856 fio_root = str(Path(__file__).absolute().parent.parent)
857 print("fio root is %s" % fio_root)
862 if platform.system() == "Windows":
866 fio_path = os.path.join(fio_root, fio_exe)
867 print("fio path is %s" % fio_path)
868 if not shutil.which(fio_path):
869 print("Warning: fio executable not found")
871 artifact_root = args.artifact_root if args.artifact_root else \
872 "fio-test-{0}".format(time.strftime("%Y%m%d-%H%M%S"))
873 os.mkdir(artifact_root)
874 print("Artifact directory is %s" % artifact_root)
876 if not args.skip_req:
877 req = Requirements(fio_root)
883 for config in TEST_LIST:
884 if (args.skip and config['test_id'] in args.skip) or \
885 (args.run_only and config['test_id'] not in args.run_only):
886 skipped = skipped + 1
887 print("Test {0} SKIPPED (User request)".format(config['test_id']))
890 if issubclass(config['test_class'], FioJobTest):
891 if config['pre_job']:
892 fio_pre_job = os.path.join(fio_root, 't', 'jobs',
896 if config['pre_success']:
897 fio_pre_success = config['pre_success']
899 fio_pre_success = None
900 if 'output_format' in config:
901 output_format = config['output_format']
903 output_format = 'normal'
904 test = config['test_class'](
906 os.path.join(fio_root, 't', 'jobs', config['job']),
908 fio_pre_job=fio_pre_job,
909 fio_pre_success=fio_pre_success,
910 output_format=output_format)
911 elif issubclass(config['test_class'], FioExeTest):
912 exe_path = os.path.join(fio_root, config['exe'])
913 if config['parameters']:
914 parameters = [p.format(fio_path=fio_path) for p in config['parameters']]
917 if Path(exe_path).suffix == '.py' and platform.system() == "Windows":
918 parameters.insert(0, exe_path)
919 exe_path = "python.exe"
920 if config['test_id'] in pass_through:
921 parameters += pass_through[config['test_id']].split()
922 test = config['test_class'](exe_path, parameters,
925 print("Test {0} FAILED: unable to process test config".format(config['test_id']))
929 if not args.skip_req:
931 for req in config['requirements']:
932 reqs_met, reason = req()
933 logging.debug("Test %d: Requirement '%s' met? %s", config['test_id'], reason,
938 print("Test {0} SKIPPED ({1})".format(config['test_id'], reason))
939 skipped = skipped + 1
942 test.setup(artifact_root, config['test_id'])
949 result = "FAILED: {0}".format(test.failure_reason)
951 contents, _ = FioJobTest.get_file(test.stderr_file)
952 logging.debug("Test %d: stderr:\n%s", config['test_id'], contents)
953 contents, _ = FioJobTest.get_file(test.stdout_file)
954 logging.debug("Test %d: stdout:\n%s", config['test_id'], contents)
955 print("Test {0} {1}".format(config['test_id'], result))
957 print("{0} test(s) passed, {1} failed, {2} skipped".format(passed, failed, skipped))
962 if __name__ == '__main__':