subprojects/gst-devtools/docs/gst-validate-flow.md

   1 ---
   2 title: Validate Flow
   3 short-description: Validate a pad data flow
   4 ...
   5
   6 # Validate Flow
   7
   8 Validate Flow — GStreamer validate component to record a log of buffers and
   9 events flowing in a specified pad and compare it with an expectation file.
  10
  11 ## Description
  12
  13 This component exists for the purpose of testing non-regular-playback use cases
  14 where the test author specifies the full pipeline, a series of actions and needs
  15 to check whether the generated buffers and events make sense.
  16
  17 The testing procedure goes like this:
  18
  19 1. The test author writes a [.validatetest](gst-validate-test-file.md) test
  20    where validateflow is used. A pad where monitoring will occur is specified
  21    and possibly a list of [actions](gst-validate-action-types.md) to run can
  22    also be specified.
  23
  24 2. The test author runs the test with the desired pipeline, the configuration
  25    and the actions. Since an expectation file does not exist at
  26    this point, validateflow will create one. The author should check its
  27    contents for any missing or unwanted events. No actual checking is done by
  28    validateflow in this step, since there is nothing to compare to yet.
  29
  30 3. Further executions of the test will also record the produced buffers and
  31    events, but now they will be compared to the previous log (expectation file).
  32    Any difference will be reported as a test failure. The original expectation
  33    file is never modified by validateflow. Any desired changes can be made by
  34    editing the file manually or deleting it and running the test again.
  35
  36 ## Example
  37
  38 ### Simplest example
  39
  40 The following is an example of a `fakesrc.simple.validatetest` file using
  41 validateflow.
  42
  43 {{ fakesrc.simple.validatetest.ini }}
  44
  45 Then generate the expectation file with:
  46
  47 ``` bash
  48 gst-validate-1.0 --set-test-file /path/to/fakesrc.simple.validatetest
  49 ```
  50
  51 This will generate the
  52 `/path/to/fakesrc.simple/flow-expectations/log-sink-sink-expected` file
  53 containing:
  54
  55 {{ plugins/fakesrc.simple/flow-expectations/log-sink-sink-expected.log }}
  56
  57 Note that the test will be marked as "SKIPPED" when we generate expectation
  58 files.
  59
  60 The test can now be run with:
  61
  62 ```
  63 gst-validate-1.0 --set-test-file /path/to/fakesrc.simple.validatetest
  64 ```
  65
  66 ### Example controlling the source
  67
  68 The following is an example of the `qtdemux_change_edit_list.validatetest` file using validateflow.
  69
  70 ``` ini
  71 set-globals, media_dir="$(test_dir)/../../../medias/"
  72 meta,
  73     seek=false,
  74     handles-states=false,
  75     args = {
  76          "appsrc ! qtdemux ! fakesink async=false",
  77     },
  78     configs = {
  79        "$(validateflow), pad=fakesink0:sink, record-buffers=false",
  80     }
  81
  82 # Scenario action types
  83 appsrc-push, target-element-name=appsrc0, file-name="$(media_dir)/fragments/car-20120827-85.mp4/init.mp4"
  84 appsrc-push, target-element-name=appsrc0, file-name="$(media_dir)/fragments/car-20120827-85.mp4/media1.mp4"
  85 checkpoint, text="A moov with a different edit list is now pushed"
  86 appsrc-push, target-element-name=appsrc0, file-name="$(media_dir)/fragments/car-20120827-86.mp4/init.mp4"
  87 appsrc-push, target-element-name=appsrc0, file-name="$(media_dir)/fragments/car-20120827-86.mp4/media2.mp4"
  88 stop
  89 ```
  90
  91 This example shows the elements of a typical validate flow test (a pipeline, a
  92 config and a scenario). Some actions typically used together with validateflow
  93 can also be seen. Notice variable interpolation is used to fill absolute paths
  94 for media files in the scenario (`$(test_dir)`). In the configuration,
  95 `$(validateflow)` is expanded to something like this, containing proper paths
  96 for expectations and actual results (these values are interpolated from the
  97 `.validatetest` file location):
  98
  99 ``` ini
 100 validateflow, expectations-dir="/validate/test/file/path/validateqtdemux_change_edit_list/flow-expectations/", actual-results-dir="$(GST_VALIDATE_LOGSDIR)/logs/validate/launch_pipeline/qtdemux_change_edit_list"
 101 ```
 102
 103 The resulting log looks like this:
 104
 105 ``` ini
 106 event stream-start: GstEventStreamStart, flags=(GstStreamFlags)GST_STREAM_FLAG_NONE, group-id=(uint)1;
 107 event caps: video/x-h264, stream-format=(string)avc, alignment=(string)au, level=(string)2.1, profile=(string)main, codec_data=(buffer)014d4015ffe10016674d4015d901b1fe4e1000003e90000bb800f162e48001000468eb8f20, width=(int)426, height=(int)240, pixel-aspect-ratio=(fraction)1/1;
 108 event segment: format=TIME, start=0:00:00.000000000, offset=0:00:00.000000000, stop=none, time=0:00:00.000000000, base=0:00:00.000000000, position=0:00:00.000000000
 109 event tag: GstTagList-stream, taglist=(taglist)"taglist\,\ video-codec\=\(string\)\"H.264\\\ /\\\ AVC\"\;";
 110 event tag: GstTagList-global, taglist=(taglist)"taglist\,\ datetime\=\(datetime\)2012-08-27T01:00:50Z\,\ container-format\=\(string\)\"ISO\\\ fMP4\"\;";
 111 event tag: GstTagList-stream, taglist=(taglist)"taglist\,\ video-codec\=\(string\)\"H.264\\\ /\\\ AVC\"\;";
 112 event caps: video/x-h264, stream-format=(string)avc, alignment=(string)au, level=(string)2.1, profile=(string)main, codec_data=(buffer)014d4015ffe10016674d4015d901b1fe4e1000003e90000bb800f162e48001000468eb8f20, width=(int)426, height=(int)240, pixel-aspect-ratio=(fraction)1/1, framerate=(fraction)24000/1001;
 113
 114 CHECKPOINT: A moov with a different edit list is now pushed
 115
 116 event caps: video/x-h264, stream-format=(string)avc, alignment=(string)au, level=(string)3, profile=(string)main, codec_data=(buffer)014d401effe10016674d401ee8805017fcb0800001f480005dc0078b168901000468ebaf20, width=(int)640, height=(int)360, pixel-aspect-ratio=(fraction)1/1;
 117 event segment: format=TIME, start=0:00:00.041711111, offset=0:00:00.000000000, stop=none, time=0:00:00.000000000, base=0:00:00.000000000, position=0:00:00.041711111
 118 event tag: GstTagList-stream, taglist=(taglist)"taglist\,\ video-codec\=\(string\)\"H.264\\\ /\\\ AVC\"\;";
 119 event tag: GstTagList-stream, taglist=(taglist)"taglist\,\ video-codec\=\(string\)\"H.264\\\ /\\\ AVC\"\;";
 120 event caps: video/x-h264, stream-format=(string)avc, alignment=(string)au, level=(string)3, profile=(string)main, codec_data=(buffer)014d401effe10016674d401ee8805017fcb0800001f480005dc0078b168901000468ebaf20, width=(int)640, height=(int)360, pixel-aspect-ratio=(fraction)1/1, framerate=(fraction)24000/1001;
 121 ```
 122
 123 ## Configuration
 124
 125 In order to use the plugin a validate configuration must be provided,
 126 containing a line starting by `validateflow` followed by a number of settings.
 127 Every `validateflow` line creates a `ValidateFlowOverride`, which listens to a
 128 given pad. A test may have several `validateflow` lines, therefore having
 129 several overrides and listening to different pads with different settings.
 130
 131 * `pad`: Required. Name of the pad that will be monitored.
 132 * `record-buffers`: Default: false. Whether buffers will be logged. By default
 133    only events are logged.
 134 * `buffers-checksum`: Default: 'none'. Define the type of checksums to be used
 135    valid values are:
 136   * `none`: No checksum recorded
 137   * `as-id`: Record checksum as 'ids' where the IDs are incremented on each new
 138              checksum passed in
 139   * `md5`: md5 checksum
 140   * `sha1`: sha1 checksum
 141   * `sha256`: sha256 checksum
 142   * `sha512`: sha512 checksum
 143   * *Note*: for backward compatibility reasons, this can be passed as a
 144             boolean and it will default to 'sha1' if true, 'none' if false.
 145 * `ignored-fields`: Default: `"stream-start={ stream-id }"` (as they are often
 146    non reproducible). Key with a serialized GstValueList(str) of fields to not
 147    record.
 148 * `logged-fields`: Default: `NULL` Key with a serialized GstValueList(str) of
 149    fields to record, eg. `logged-event-fields="stream-start={flags},
 150    caps={width, height, framerate}, buffer={pts}"`. Overrides
 151    `ignored-event-fields` for specified event types.
 152 * `ignored-event-types`: Default: `{ }`. List of event type names to not record
 153 * `logged-event-types`: Default: `NULL`. List of event type names to not record,
 154    if noone provided, all events are logged, except the ones defined in the
 155    `ignored-event-types`.
 156 * `expectations-dir`: Path to the directory where the expectations will be
 157    written if they don't exist, relative to the current working directory. By
 158    default the current working directory is used, but this setting is usually
 159    set automatically as part of the `%(validateflow)s` expansion to a correct
 160    path like `~/gst-validate/gst-integration-testsuites/flow-expectations/<test
 161    name>`.
 162 * `actual-results-dir`: Path to the directory where the events will be recorded.
 163    The expectation file will be compared to this. By default the current working
 164    directory is used, but this setting is usually set automatically as part of
 165    the `%(validateflow)s` expansion to the test log directory, i.e.
 166    `~/gst-validate/logs/validate/launch_pipeline/<test name>`.
 167 * `generate-expectations`: Default: unset. When set to `true` the expectation
 168    file will be written and no testing will be done and if set to `false`, the
 169    expectation file will be required. If a validateflow config is used without
 170    specifying any other parametters, the validateflow plugin will consider that
 171    all validateflow overrides will use that value.
 172
 173
 174 ## Scenario actions
 175
 176 Scenarios with validateflow work in the same way as other tests. Often
 177 validatetests will use appsrc in order to control the flow of data precisely,
 178 possibly interleaving events in between. The following is a list of useful
 179 actions.
 180
 181  * `appsrc-push`: Pushes a buffer from an appsrc element and waits for the chain
 182    operation to finish. A path to a file is provided, optionally with an offset
 183    and/or size.
 184  * `appsrc-eos`: Queues an EOS event from the appsrc. The action finishes
 185    immediately at this point.
 186  * `stop`: Tears down the pipeline and stops the test.
 187  * `checkpoint`: Records a "checkpoint" message in all validateflow overrides,
 188    with an optional explanation message. This is useful to check certain events
 189    or buffers are sent at a specific moment in the scenario, and can also help
 190    to the comprehension of the scenario.
 191
 192 More details on these actions can be queried from the command line, like this:
 193
 194 ``` bash
 195 gst-validate-1.0 --inspect-action-type appsrc-push
 196 ```