Skip to content

Foretify invocation

Purpose

Launch Foretify.

Syntax

foretify [<option1> <option2> ...]

Options

--batch

Quit after running batch commands. (Default: interactive).

--commands <command-list>

Specify commands to execute after the run. To execute multiple commands, separate them with a semi-colon, or enter a list of batch commands in the configuration file. Commands that include spaces must be enclosed in quotes. See Flow parameter processing to learn when batch commands are executed.

--config <pathname>

Specify a file that configures the invocation. On startup, Foretify checks for a configuration file in the path ~/.foretify.cfg. If the file exists, it is loaded. You must specify files with other names or locations explicitly with the --config invocation option.

--cover_max_buckets <int>

Specify the maximum number of buckets per item.

--crun <int>

The number of times to run consecutive tests of the same test. The initial seed is incremented by 1 for each run. (Default: 0).

--crun_seeds <list-of-seeds>

Make consecutive runs of the same test using the specified list of seeds. <list-of-seeds> is a comma-separated list of seeds enclosed in quotes, for example: "1,3,5".

--debug_record

Enable recording of simulation data. You can record a Foretify test execution in your environment and send the run results to Foretellix for replay. This shipped data enables Foretify to reproduce the entire run on the Foretify side without depending on other components, such as the SSP/Simulator and DSP/SUT.

--debug_replay <path-to-run-dir>

A path to a run folder to replay. Use this command to replay a run recorded in a full environment (including SSP, a simulator and DSP, SUT) in a reduced environment that does not contain the simulator or SUT. If the original run was performed with limited ROI, re-running will use the same ROI.

Note

You can load OSC2 files with the --debug_replay and --run options in order to add or modify coverage items, traces or checks on top of the existing scenarios without actually re-running the test as long as the additions do not have any influence on simulation or SUT behavior. The syntax for this is:

Shell command: replay a recorded run
$ foretify --debug_replay /tmp/debug_record
        --run
        --load <additional_coverage.osc>
        --load <additional_checks.osc>
        --load <additional_traces.osc>

--demo

Run Foretify in demo mode.

--display_units <physical-type> <unit>

Set the display unit for a physical type. By default, every physical type is displayed using its SI unit (for example, length by meter and speed by mps), with the exception of temperature which is displayed in Celsius. Use this option to override the default display unit for any physical type. You can specify this option multiple times for different physical types.

Shell command: set display units
$ foretify --display_units temperature fahrenheit --display_units speed kph

You can also set display units in a YAML configuration file. See Display unit options.

--dlog_frpc trace

Provide additional log information about Foretify’s communication with the SSP and DSP components. Specifically, include the fRPC requests sent from Foretify to the SSP and DSP, along with the parameter values of each request, in the scenario execution log.

--enable_status_server

Enable the Foretify status server.

The status server is accessible on: http://localhost:/status and http://localhost:/version.

See --status_server_port. See also Server status for endpoints and status values.

--gen_file_name <name>

This option specifies the name of the test file to be generated.

--gui

Enable the Foretify graphical user interface via a web browser and open the browser on the local server. (Default: false).

--help

Display invocation options for Foretify.

--help_config

Display configuration options for Foretify.

--job_id <id>

Specify an ID for Foretify test run, will be written to run_info.json file.

--keepalive_timeout <number-of-seconds>

A non-negative integer specifying a timeout in seconds for Foretify's runtime engine. A value of 0 disables the timeout. The default is 60. This setting is relevant only when using batch mode (--batch)

By default, Foretify waits for up to 60 seconds for a keep-alive message from its runtime engine. This engine operates during scenario execution, not during generation. If the runtime engine does not respond with a message within the defined timeout, Foretify terminates the run.

You can increase the timeout if you see many incomplete runs with the (normalized) message: "Runtime engine did not respond". Alternatively, you can reduce the timeout in order to speed up test suites, but more runs may not be successfully executed.

Note

If you see many incomplete runs without the "Runtime engine did not respond" message, it is better to set a user-defined timeout with --run_timeout because that option allows more time for generation, as well as for execution.

--lint <level>

Specify one of the following as the level:

  • ignore: the linter is not activated. This is the default mode.

  • warn: the linter is activated and a warning is issued for every violation.

  • error: the linter is activated and an error is issued for every violation. In this mode any lint issue causes the load process to fail.

--lint_config <pathname>

A text file specifying a list of named rules and their severity level. If the configuration file specifies a rule name or level that does not exist an error is flagged and the load fails.

--load <pathname>

An OSC2 file to load. Use multiple --load options to execute multiple commands, or enter a list of load commands in the configuration file. (Default extension: osc).

--load_run <pathname>

Load a previously executed run. The parameter is a path to a run folder. If the original run was performed with limited ROI, loaded data will include the original ROI.

--main <scenario-name>

Specify the name of the scenario to be added to top.main. This option is used to generate a test file.

--map <pathname>

Path to test map file. This option is used to generate a test file.

--match <pathname>

Invokes the Evaluation Pipeline flow. Provide the path to the OSC2 top-level file that includes the match scenarios.

--physical_type_display_precision <int>

Define the number of digits to display after the decimal point for physical types. Valid values are 0 to 17. (Default: 2).

Shell command: set physical type display precision
$ foretify --physical_type_display_precision 4

--port <port-id>

Set a web-server listening port for the graphical interface explicitly. (Default: 8060).

--pre_commands <command-list>

Batch commands to execute before the run. To execute multiple commands, separate them with a semi-colon, or enter a list of batch commands in the configuration file. Commands that include spaces must be enclosed in quotes. See Flow parameter processing to learn when batch commands are executed.

--print-order-lexicography

When printing using the print command, display fields in alphabetical order.

--record_video

With this option, a video clip is automatically created for each run by taking a snapshot of the scenario every 100ms. The mp4 format file is saved into the runs directory with the name scene_movie.

This facilitates monitoring of the executed scenarios without needing to run interactively.

Note

This feature is simulator dependent. It may require the simulator to work in full GUI mode (not headless) in order to record properly.

--run

Run loaded/generated test file. (Default: false).

--run_timeout <number-of-seconds>

A non-negative integer specifying the timeout, in seconds, for a single test run. A value of 0 disables the timeout (default setting). This setting is relevant only when using batch mode (--batch)

By default, Foretify may terminate a run if there is some delay in generation or execution. If you see many incomplete runs, you can set a timeout to allow more time for the run to continue.

If a run exceeds the specified timeout, you will see a normalized message indicating the phase in which the timeout occurred. For example, if the timeout happens during generation, the normalized message will be: "Test generation exceeded user specified timeout". If the timeout occurs during execution, the message will be: "Test duration exceeded the timeout during the execution stage". The full message will also include the configured timeout, and if the timeout occurred during execution, it will include the duration of the generation phase. For example: "Test duration exceeded user specified timeout : 360 seconds (timeout configurable as --run_timeout), during stage: execution, generation duration: 100 seconds".

Note

If you see the (normalized) message: "Runtime engine did not respond", you should adjust the timeout for the runtime engine with --keepalive_timeout.

--generation_timeout <number-of-seconds>

A non-negative integer specifying the timeout, in seconds, for a single generation phase. A value of 0 disables the timeout (default setting). This setting is relevant only when using batch mode (--batch)

By default, Foretify may terminate a run if there is a delay in the generation process. If you notice frequent incomplete runs, you can set a timeout to allow more time for the run to complete.

If the generation exceeds the specified timeout, the normalized message will be: "Test duration exceeded timeout during generation stage". The full message will include the configured timeout and the duration of the generation phase. For example: "Test generation exceeded user specified timeout: 3600 seconds (timeout configurable as --generation_timeout)".

Note

You can specifiy both --generation_timeout and --run_timeout. In this case, the generation phase will not exceed the generation_timeout value, and the total run time (including generation time) will not the exceed the run_timeout value.

--seed <int>

Specifies the seed to be used for the first test. Valid values are any number in the range of 1 to 2147483647, or the word random. When random is used with --crun, the seed is incremented for each subsequent run rather than being generated randomly again. (Default: 1).

--server [true]

Enable Foretify server. (Default: false).

--set <field-name>=<value>

Assign values to the fields defined in the config struct of top, using this syntax:

Foretify invocation: --set syntax
 config.<struct>.<field>=<value>.
Foretify invocation: --set example
$ foretify --load my_top.osc --set config.sim.speed_factor=1

When setting string fields, they should be escaped, as shown in the following example:

Foretify invocation: --set example for string
$ foretify --load my_top.osc --set config.test.test_name=\"test\"

--status_server_port <port-id>

Set explicit status server listening port.

See --enable_status_server. See also Server status.

--trace_issues

Enables tracing of run issues.

--verbosity <level>

Set the level of messages you want to be displayed, one of ERROR, INFO (default), DEBUG, TRACE.

--version

Display Foretify version number.

--work_dir <pathname>

Foretify work directory. (Default: /foretify).

Description

Invocation options take precedence over options set by the YAML configuration.