subprojects/gst-devtools/docs/gst-validate-test-file.md

   1 ---
   2 title: Test file
   3 short-description: GstValidate test file
   4 ...
   5
   6 # GstValidate Test file
   7
   8 A `.validatetest` file describes a fully contained validate test case. It
   9 includes the arguments of the tool supposed to be used to run the test as well
  10 as possibly a [configuration](gst-validate-config.md) and a set of action to
  11 describe the validate [scenario](gst-validate-scenarios.md).
  12
  13 # The file format
  14
  15 A validate test file requires a `meta` structure which contains the same
  16 information as the [scenario](gst-validate-scenarios.md) `meta` with some
  17 additional fields described below. The `meta` structure should be either the
  18 first or the one following the `set-globals` structure. The `set-globals`
  19 structures allows you to set global variables for the rest of the
  20 `.validatetest` file and is a free form variables setter. For example you can
  21 do:
  22
  23 ``` yaml
  24 set-globals, media_dir=$(test_dir)/../../media
  25 ```
  26
  27 ## Tool arguments
  28
  29 In the case of [`gst-validate`](gst-validate.md) it **has to** contain an
  30 `args` field with `gst-validate` argv arguments like:
  31
  32 ``` yaml
  33 # This is the default tool so it is not mandatory for the `gst-validate` tool
  34 tool = "gst-validate-$(gst_api_version)",
  35 args = {
  36     # pipeline description
  37     videotestrc num-buffers=2 ! $(videosink),
  38     # Random extra argument
  39     --set-media-info $(test-dir)/some.media_info
  40 }
  41 ```
  42
  43 ## configs
  44
  45 The `configs` field is an array of structures containing the same content as
  46 usual [configs](gst-validate-config.md) files.
  47
  48 For example:
  49
  50 ``` yaml
  51 configs = {
  52     # Set videotestsrc0 pattern value to `blue`
  53     "core, action=set-property, target-element-name=videotestsrc0, property-name=pattern, property-value=blue",
  54     "$(validateflow), pad=sink1:sink, caps-properties={ width, height };",
  55 }
  56 ```
  57
  58 Note: Since this is GstStructure synthax, we need to have the structures in the
  59 array as strings/within quotes.
  60
  61 ## expected-issues
  62
  63 The `expected-issues` field is an array of `expected-issue` structures containing
  64 information about issues to expect (which can be known bugs or not).
  65
  66 Use `gst-validate-1.0 --print-issue-types` to print information about all issue types.
  67
  68 For example:
  69
  70 ``` yaml
  71 expected-issues = {
  72     "expected-issue, issue-id=scenario::not-ended",
  73 }
  74 ```
  75
  76 Note: Since this is GstStructure synthax, we need to have the structures in the
  77 array as strings/within quotes.
  78
  79 ### Fields:
  80
  81 * `issue-id`: (string): Issue ID - Mandatory if `summary` is not provided.
  82 * `summary`: (string): Summary - Mandatory if `issue-id` is not provided.
  83 * `details`: Regex string to match the issue details `detected-on`: (string):
  84              The name of the element the issue happened on `level`: (string):
  85              Issue level
  86 * `sometimes`: (boolean): Default: `false` -  Wheteher the issue happens only
  87                sometimes if `false` and the issue doesn't happen, an error will
  88                be issued.
  89 * `issue-url`: (string): The url of the issue in the bug tracker if the issue is
  90                a bug.
  91
  92 ### Variables
  93
  94 The same way
  95
  96 Validate testfile will define some variables to make those files relocable:
  97
  98 * `$(test_dir)`: The directory where the `.validatetest` file is in.
  99
 100 * `$(test_name)`: The name of the test file (without extension).
 101
 102 * `$(test_name_dir)`: The name of the test directory (test_name with folder
 103                       separator instead of `.`).
 104
 105 * `$(validateflow)`: The validateflow structure name with the default/right
 106                      values for the `expectations-dir` and `actual-results-dir`
 107                      fields. See [validateflow](gst-validate-flow.md) for more
 108                      information.
 109
 110 * `$(videosink)`: The GStreamer videosink to use if the test can work with
 111                   different sinks for the video. It allows the tool to use
 112                   fakesinks when the user doesn't want to have visual feedback
 113                   for example.
 114
 115 * `$(audiosink)`: The GStreamer audiosink to use if the test can work with
 116                   different sinks for the audio. It allows the tool to use
 117                   fakesinks when the user doesn't want to have audio feedback
 118                   for example.