Test Runner Syntax Options

Use the following syntax from the shell prompt to run a test suite.

At the prompt, enter:

test-runner [options] [test-suite] 

where:

test-runner
The name of the executable that will run the test suite, and then produce the test results:
  • cobmfurunil8 - for use with .NET COBOL (.NET 8 specific) ; see Unit Testing Support for .NET 8
  • cobmfurun32[_t] - for use with procedural COBOL
  • cobmfurun64[_t] - for use with procedural COBOL
  • cobmfurunj - for use with JVM COBOL

The optional _t runs the test suite in the multi-threaded run-time system, and is required for tests that use a timeout value.

options

The options that apply to the test run. These are optional, and you can apply one or more of the following:

-testcase:testcase-name
Only run the specified test case from the test suite; all other test cases are skipped. Not set by default.

Alternatively, you can specify multiple test cases using one of the following approaches:

  • List the test cases using comma as a separator:
    -testcase:testcase-name1,testcase-name2,... everything.dll

    Or:

  • Specify a side file that includes a list of test cases:
    -testcase:@filelist.txt everything.dll

Where:

  • everything.dll - all your source code compiled
  • filelist.txt - the file that includes a list of all test cases to execute
-ignore-options-in-mfu:{true|false}
Ignores any options in the specified test fixture file, enabling you to override them with ones specified on the command line.
-ignore-return-code:{true|false}
When set to true, the return-code indicating a test pass or fail is ignored, and the test continues running. The default is false.
-verbose:{true|false}
Displays verbose output to the screen. The default is true.
-process:{single|separate}
Use a single process for the entire test run, or multiple separate processes (one for the test runner and one for each test case within the run). If you are using separate processes, the parent test runner process can log errors and continue with the test run in the event of a test case failure. The default is separate.
-isolate:{true|false}
Isolates each test case, so that any resources shared between test cases start from their correct initial state for each test case. The default is true.
-report:{printfile|noprintfile|junit|nojunit}...
Outputs the test results to a .txt file (printfile option) or .xml file (junit option). The default is to produce a .txt file. The JUnit report takes the form of TEST-<package-name>-<test-case-name>.xml. Set <package-name> using the -junit-packname:package-name option.
-generate-flist:filename
Outputs a list of failed test names to filename.
Tip: You can use the generated file to rerun the failed tests by using the -testcase:@filename test-suite syntax.
-report:markdown
Outputs the test results to a GitHub style markdown format file (.md).
Note: You can use various external utilities such as the pandoc utility (see http://pandoc.org/) to convert the markdown file into an .html or a .pdf file. Here are some example commands for converting the .md file when you use pandoc:
pandoc -thtml5 -s -S --toc -c pandoc.css -fmarkdown_github mfumeta.md -o mfumeta.html

Or

pandoc -s -S --toc -c pandoc.css -fmarkdown_github mfumeta.md -o mfumeta.pdf
-report:timings-csv
Generates a .csv file containing the timings for the test run.
-reportfile:filename
Changes the name of the report file. It defaults to <test suite-name>-report.txt.
-junit-packname:package-name
Packages the JUnit formatted .xml files under package-name. Not set by default.
-generate-app-exe-ep:entry-point
When running tests against an executable file, you need to generate a replacement main entry point for your executable that is capable of calling the Micro Focus Unit Testing Framework. This command generates a source file, mfunit_application_entrypoint.cbl, that contain such an entry point. Build this into your executable so that it can be run against a set of tests when executed within the framework. When run outside of the framework, this entry point is not called, and the executable runs as normal.
-application-exe:executable-file
Runs tests against an executable file. The executable must have been re-built to include the mfunit_application_entrypoint.cbl produced using the option above.
-outdir:directory
Specifies a directory for the reports. If not specified, the reports are created in the directory in which the tests were run.
-trait:trait-name(s)
Specifies that only test cases with the specified trait name should be run (and all other test cases skipped). You can specifiy more than one trait, separated by a comma, if required. You set a trait for a test case by using the MFU-MD-TRAITS variable in your source code, or specifying the traits=trait-name in the text fixture file.
Tip: You can combine this option with the -generate-mfu option to create a test fixture file designed to only run test cases with a particular trait; for example:
cobmfurun32|64[_t] -generate-mfu -trait:smoke test-suite.so
-jenkins-ci
Enables support for producing test results that will be used on a Jenkins CI server.
-jenkins-ci:junit-attachments
Enables support for producing test results that will be used on a Jenkins CI server, and also enables the Jenkins plugin for JUnit formatted results.
-diagnostics-color:off|ansi|jenkins|windows10
Enables colorisation of certain elelments of the output. Set the value to the intended viewing platform. The default is off. See Using Color in Test Reports for more information.
-silk-central

Outputs the results to an .xml file that is compatible with Silk Central. The output.xml file, along with any required assets (log and dump files), are placed in the location determined by the SCTM_EXEC_RESULTSFOLDER environment variable, where they can be picked up and processed by Silk Central (refer to your Silk Central Help for more information on ProcessExecuter Tests). If you specify this option when your Silk Central environment is not correctly configured, you receive an error.

-jit:{core|debug}
Produces a core dump file or invokes just-in-time debugging when a test case errors.
Note: This option has no effect when asserting a test failure.
-debugbreak
Immediately starts the debugger.
-debugger:debug-engine
Invokes the specified debugger. The permissible values are vscode (where the native debugger, provided by the Micro Focus COBOL extension in VS Code, is used) or eclipse (UNIX only, where the Eclipse debugger is used).
-debugstart:id
Issues a start/wait command to the debugger using the specified id.
-csv-line-filter:line-number testcase-name
For use when executing data-driven tests for a data source in CSV format. Use line-number to specify the only line of your data source to use when running testcase-name. This can be particularly useful when combined with the -debugbreak and -debugstart options to focus in on a particular piece of data.
-generate-csv-snippet:testcase-name data-source
Creates a test case that includes the basic structure for a data-driven test. It reads data-source (currently limited to CSV files) and creates the necessary data items required to test the data.
Note: Windows users: you can directly pipe the code snippet to the clipboard by appending | clip to the command.
-generate-mfu filename
Produces a skeleton test fixture file (.mfu file) from the test cases within filename (a .dll file or .so file).
-high-res-timer:{true|false}
When set to true, a native high-resolution performance counter is used to report the duration of the test run. The default is false.
Note: High-resolution timings cannot be displayed in the junit or Silk Central .xml formats; normal timings are always displayed.
generate-exec-mock-snippet:options
Generates a source file that can be used when mocking a program containing EXEC statements (EXEC SQL).This option requires a catalog file (with an mfupp-et extension), which is produced using the EXEC-REPORT-FILE directive of the MFUPP pre-processor. This parameter takes the following options, which determines the content of the snippets produced:
Option Abbreviation Default Description
regions r off Generate regions
noregions nor on Do not generate regions
comment-vars cv on Include comments relating to the fields in use
nocomment-vars nocv off Do not include comments relating to the fields in use
init-vars iv on Generate move or initialize statements for fields in use
noinit-vars noiv off Do not generate move or initialize statements for fields in use
data-driven dd off Create a data driven csv file header from all fields in use
nodata-driven nodd on Do not create a data driven csv file header
skip-default-sid sdsid off Skip the creation of EXEC SQL statement if no custom MFUPP-SID ID is given
test-suite
A COBOL program compiled to .so , or an .mfu test fixture file. For procedural managed program, specify a .jar file instead.
Tip: Use the following command to obtain a list of shortened arguments that you can use when running tests:
cobmfurun32|64[_t] -shortcuts