validate: Update action types documentation

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/3040>

subprojects/gst-devtools/docs/gst-validate-action-types.md

@@ -1,10 +1,10 @@
 # GstValidate action types
-
 ## meta
 
 
 ``` validate-scenario
 meta,
+    [allow-errors=(boolean)],
     [duration=(double, int)],
     [handles-states=(boolean)],
     [ignore-eos=(boolean)],
@@ -28,6 +28,13 @@ NOTE: it used to be called "description"
 
 ### Parameters
 
+* `allow-errors`:(optional): Ignore error messages and keep executing the
+scenario when it happens. By default a 'stop' action is generated on ERROR messages
+
+  Possible types: `boolean`
+
+  Default: false
+
 * `duration`:(optional): Lets the user know the time the scenario needs to be fully executed
 
   Possible types: `double, int`
@@ -407,9 +414,14 @@ int: To use the actual index to use`
 
 ``` validate-scenario
 wait,
+    [check=(structure)],
     [duration=(double or string (GstClockTime))],
+    [expected-values=(structure)],
     [message-type=(string)],
+    [non-blocking=(string)],
+    [on-clock=(boolean)],
     [signal-name=(string)],
+    [target-element-factory-name=(string)],
     [target-element-name=(string)],
     [playback-time=(double,string)];
 ```
@@ -419,19 +431,51 @@ Waits for signal 'signal-name', message 'message-type', or during 'duration' sec
 
 ### Parameters
 
+* `check`:(optional): The check action to execute when non blocking signal is received
+
+  Possible types: `structure`
+
+  Default: (null)
+
 * `duration`:(optional): the duration while no other action will be executed
 
   Possible types: `double or string (GstClockTime)`
 
   Default: (null)
 
+* `expected-values`:(optional): Expected values in the message structure (valid only when `message-type`). Example: wait, on-client=true, message-type=buffering, expected-values=[values, buffer-percent=100]
+
+  Possible types: `structure`
+
+  Default: (null)
+
 * `message-type`:(optional): The name of the message type to wait for (on @target-element-name if specified)
 
   Possible types: `string`
 
   Default: (null)
 
-* `signal-name`:(optional): The name of the signal to wait for on @target-element-name
+* `non-blocking`:(optional): **Only for signals**.Make the action non blocking meaning that next actions will be
+executed without waiting for the signal to be emitted.
+
+  Possible types: `string`
+
+  Default: (null)
+
+* `on-clock`:(optional): Wait until the test clock gets a new pending entry.
+See #gst_test_clock_wait_for_next_pending_id.
+
+  Possible types: `boolean`
+
+  Default: (null)
+
+* `signal-name`:(optional): The name of the signal to wait for on @target-element-name. To ensure that the signal is executed without blocking while waiting for it you can set the field 'non-blocking=true'.
+
+  Possible types: `string`
+
+  Default: (null)
+
+* `target-element-factory-name`:(optional): The name factory for which to wait @signal-name on
 
   Possible types: `string`
 
@@ -521,6 +565,24 @@ Changes the ranking of a particular plugin feature(s)
 
   Possible types: `string, int`
 
+## remove-feature
+
+
+``` validate-scenario
+remove-feature,
+    name=(string);
+```
+
+Remove a plugin feature(s) or a plugin from the registry
+ * Implementer namespace: core
+ * Is config action (meaning it will be executing right at the beginning of the execution of the pipeline)
+
+### Parameters
+
+* `name`:(mandatory): The name of a GstFeature or GstPlugin to remove
+
+  Possible types: `string`
+
 ## set-feature-rank
 
 
@@ -603,6 +665,160 @@ For example you can define vars for buffer checksum to be used in the "check-las
 
 ### Parameters
 
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+  Possible variables:
+
+  * `position`: The current position in the stream
+
+  * `duration`: The duration of the stream
+
+  Possible types: `double,string`
+
+  Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+  Possible types: `string`
+
+  Default: (null)
+
+## set-timed-value-properties
+
+
+``` validate-scenario
+set-timed-value-properties,
+    timestamp=(string or float (GstClockTime)),
+    [binding-type=(string)],
+    [interpolation-mode=(string)],
+    [source-type=(string)],
+    [playback-time=(double,string)];
+```
+
+Sets GstTimedValue on pads on elements properties using GstControlBindings
+and GstControlSource as defined in the parameters.
+The properties values to set will be defined as:
+
+```
+element-name.padname::property-name=new-value
+```
+
+> NOTE: `.padname` is not needed if setting a property on an element
+
+This action also adds necessary control source/control bindings.
+
+ * Implementer namespace: core
+
+### Parameters
+
+* `timestamp`:(mandatory): The timestamp of the keyframe
+
+  Possible types: `string or float (GstClockTime)`
+
+* `binding-type`:(optional): The name of the type of binding to use
+
+  Possible types: `string`
+
+  Default: direct
+
+* `interpolation-mode`:(optional): The name of the GstInterpolationMode to set on the source
+
+  Possible types: `string`
+
+  Default: linear
+
+* `source-type`:(optional): The name of the type of ControlSource to use
+
+  Possible types: `string`
+
+  Default: GstInterpolationControlSource
+
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+  Possible variables:
+
+  * `position`: The current position in the stream
+
+  * `duration`: The duration of the stream
+
+  Possible types: `double,string`
+
+  Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+  Possible types: `string`
+
+  Default: (null)
+
+## check-properties
+
+
+``` validate-scenario
+check-properties,
+    [playback-time=(double,string)];
+```
+
+Check elements and pads properties values.
+The properties values to check will be defined as:
+
+```
+element-name.padname::property-name
+```
+
+> NOTE: `.padname` is not needed if checking an element property
+
+
+ * Implementer namespace: core
+
+### Parameters
+
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+  Possible variables:
+
+  * `position`: The current position in the stream
+
+  * `duration`: The duration of the stream
+
+  Possible types: `double,string`
+
+  Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+  Possible types: `string`
+
+  Default: (null)
+
+## set-properties
+
+
+``` validate-scenario
+set-properties,
+    [playback-time=(double,string)];
+```
+
+Set elements and pads properties values.
+The properties values to set will be defined as:
+
+```
+    element-name.padname::property-name
+```
+
+> NOTE: `.padname` is not needed if set an element property
+
+
+ * Implementer namespace: core
+
+### Parameters
+
 * `playback-time`:(optional): The playback time at which the action will be executed
 
   Possible variables:
@@ -630,6 +846,7 @@ For example you can define vars for buffer checksum to be used in the "check-las
 set-property,
     property-name=(string),
     property-value=(The same type of @property-name),
+    [on-all-instances=(boolean)],
     [target-element-factory-name=(string)],
     [target-element-klass=(string)],
     [target-element-name=(string)],
@@ -651,6 +868,12 @@ Besides property-name and value, either 'target-element-name' or
 
   Possible types: `The same type of @property-name`
 
+* `on-all-instances`:(optional): Whether to set property on all instances matching the requirements
+
+  Possible types: `boolean`
+
+  Default: (null)
+
 * `target-element-factory-name`:(optional): The name factory for which to set a property on built elements
 
   Possible types: `string`
@@ -806,6 +1029,7 @@ See gst_debug_set_threshold_from_string
 emit-signal,
     signal-name=(string),
     target-element-name=(string),
+    [params=(ValueArray)],
     [playback-time=(double,string)];
 ```
 
@@ -822,6 +1046,12 @@ Emits a signal to an element in the pipeline
 
   Possible types: `string`
 
+* `params`:(optional): The signal parameters
+
+  Possible types: `ValueArray`
+
+  Default: (null)
+
 * `playback-time`:(optional): The playback time at which the action will be executed
 
   Possible variables:
@@ -1107,11 +1337,8 @@ Checks the last-sample checksum or frame number (set on its  GstVideoTimeCodeMet
 
 ``` validate-scenario
 crank-clock,
-    [checksum=(string)],
     [expected-elapsed-time=(GstClockTime)],
     [expected-time=(GstClockTime)],
-    [sinkpad-caps=(string)],
-    [timecode-frame-number=(string)],
     [playback-time=(double,string)];
 ```
 
@@ -1120,12 +1347,6 @@ Crank the clock, possibly checking how much time was supposed to be waited on th
 
 ### Parameters
 
-* `checksum`:(optional): The reference checksum of the buffer.
-
-  Possible types: `string`
-
-  Default: (null)
-
 * `expected-elapsed-time`:(optional): Check time elapsed during the clock cranking
 
   Possible types: `GstClockTime`
@@ -1138,18 +1359,6 @@ Crank the clock, possibly checking how much time was supposed to be waited on th
 
   Default: (null)
 
-* `sinkpad-caps`:(optional): The caps (as string) of the sink to check.
-
-  Possible types: `string`
-
-  Default: (null)
-
-* `timecode-frame-number`:(optional): The frame number of the buffer as specified on its GstVideoTimeCodeMeta
-
-  Possible types: `string`
-
-  Default: (null)
-
 * `playback-time`:(optional): The playback time at which the action will be executed
 
   Possible variables:
@@ -1278,14 +1487,6 @@ If not set, GST_CLOCK_TIME_NONE will be used so upstream elements will produce a
 ``` validate-scenario
 check-position,
     expected-position=(GstClockTime),
-    [all-headers=(boolean)],
-    [count=(int)],
-    [pad=(string)],
-    [running-time=(double or string)],
-    [srcpad=(string)],
-    [target-element-factory-name=(string)],
-    [target-element-klass=(string)],
-    [target-element-name=(string)],
     [playback-time=(double,string)];
 ```
 
@@ -1299,54 +1500,75 @@ Check current pipeline position.
 
   Possible types: `GstClockTime`
 
-* `all-headers`:(optional): TRUE to produce headers when starting a new key unit
+* `playback-time`:(optional): The playback time at which the action will be executed
-
-  Possible types: `boolean`
-
-  Default: FALSE
-
-* `count`:(optional): integer that can be used to number key units
-
-  Possible types: `int`
-
-  Default: 0
-
-* `pad`:(optional): The name of the GstPad to send a send force-key-unit to
-
-  Possible types: `string`
-
-  Default: sink
-
-* `running-time`:(optional): The running_time can be set to request a new key unit at a specific running_time.
-If not set, GST_CLOCK_TIME_NONE will be used so upstream elements will produce a new key unit as soon as possible.
 
   Possible variables:
 
-  * position: The current position in the stream
+  * `position`: The current position in the stream
 
-  * duration: The duration of the stream
+  * `duration`: The duration of the stream
 
-  Possible types: `double or string`
+  Possible types: `double,string`
 
-  Default: (null)
+  Default: 0.0
 
-* `srcpad`:(optional): The name of the GstPad to send a send force-key-unit to
+* `on-message`:(optional): Specify on what message type the action will be executed.
-
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
-  Possible types: `string`
+ on whatever happens first.
-
-  Default: src
-
-* `target-element-factory-name`:(optional): The factory name of the GstElements to send a send force-key-unit to
 
   Possible types: `string`
 
   Default: (null)
 
-* `target-element-klass`:(optional): The klass of the GstElements to send a send force-key-unit to
+## check-current-pad-caps
+
+
+``` validate-scenario
+check-current-pad-caps,
+    [comparison-type=(string in [intersect, equal])],
+    [expected-caps=(caps,structure)],
+    [pad=(string)],
+    [target-element-factory-name=(string)],
+    [target-element-klass=(string)],
+    [target-element-name=(string)],
+    [playback-time=(double,string)];
+```
+
+Check currently set caps on a particular pad.
+
+ * Implementer namespace: core
+
+### Parameters
+
+* `comparison-type`:(optional): __No description__
+
+  Possible types: `string in [intersect, equal]`
+
+  Default: (null)
+
+* `expected-caps`:(optional): The expected caps. If not present, expected no caps to be set
+
+  Possible types: `caps,structure`
+
+  Default: (null)
+
+* `pad`:(optional): The name of the GstPad to get pad from
 
   Possible types: `string`
 
-  Default: Video/Encoder
+  Default: (null)
+
+* `target-element-factory-name`:(optional): The factory name of the GstElements to get pad from
+
+  Possible types: `string`
+
+  Default: (null)
+
+* `target-element-klass`:(optional): The klass of the GstElements to get pad from
+
+  Possible types: `string`
+
+  Default: (null)
 
 * `target-element-name`:(optional): The name of the GstElement to send a send force-key-unit to
 
@@ -1374,6 +1596,98 @@ If not set, GST_CLOCK_TIME_NONE will be used so upstream elements will produce a
 
   Default: (null)
 
+## run-command
+
+
+``` validate-scenario
+run-command,
+    argv=((string){array,}),
+    [env=(structure)],
+    [playback-time=(double,string)];
+```
+
+Run an external command.
+
+ * Implementer namespace: core
+
+### Parameters
+
+* `argv`:(mandatory): The subprocess arguments, include the program name itself
+
+  Possible types: `(string){array,}`
+
+* `env`:(optional): Extra environment variables to set
+
+  Possible types: `structure`
+
+  Default: (null)
+
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+  Possible variables:
+
+  * `position`: The current position in the stream
+
+  * `duration`: The duration of the stream
+
+  Possible types: `double,string`
+
+  Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+  Possible types: `string`
+
+  Default: (null)
+     optional                   : Don't raise an error if this action hasn't been executed or failed
+                                  ### Possible types:
+                                    boolean
+                                  Default: false
+
+## foreach
+
+
+``` validate-scenario
+foreach,
+    actions=({array of [structures]}),
+    [playback-time=(double,string)];
+```
+
+Run actions defined in the `actions` array the number of times specified
+with an iterator parameter passed in. The iterator can be
+a range like: `i=[start, end, step]` or array of values
+such as: `values=<value1, value2>`.
+One and only one iterator field is supported as parameter.
+ * Implementer namespace: core
+
+### Parameters
+
+* `actions`:(mandatory): The array of actions to repeat
+
+  Possible types: `{array of [structures]}`
+
+* `playback-time`:(optional): The playback time at which the action will be executed
+
+  Possible variables:
+
+  * `position`: The current position in the stream
+
+  * `duration`: The duration of the stream
+
+  Possible types: `double,string`
+
+  Default: 0.0
+
+* `on-message`:(optional): Specify on what message type the action will be executed.
+ If both 'playback-time' and 'on-message' is specified, the action will be executed
+ on whatever happens first.
+
+  Possible types: `string`
+
+  Default: (null)
+
 ## corrupt-socket-recv
 
 

subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c

@@ -6715,8 +6715,8 @@ register_action_types (void)
       },
       {
         .name = "allow-errors",
-        .description = "Ignore error messages and keep executing the scenario when it happens.\n By default "
+        .description = "Ignore error messages and keep executing the\n"
-          "a 'stop' action is generated one ERROR messages",
+          "scenario when it happens. By default a 'stop' action is generated on ERROR messages",
         .mandatory = FALSE,
         .types = "boolean",
         .possible_variables = NULL,
@@ -6882,7 +6882,8 @@ register_action_types (void)
         {
           .name = "non-blocking",
           .description = "**Only for signals**."
-            " Ensures that the signal is emitted without a blocking waiting.",
+            "Make the action non blocking meaning that next actions will be\n"
+            "executed without waiting for the signal to be emitted.",
           .mandatory = FALSE,
           .types = "string",
           NULL
@@ -6901,13 +6902,13 @@ register_action_types (void)
             "`message-type`). Example: "
             "wait, on-client=true, message-type=buffering, expected-values=[values, buffer-percent=100]",
           .mandatory = FALSE,
-          .types = "GstStructure",
+          .types = "structure",
           NULL
         },
         {
           .name = "on-clock",
-          .description = "Wait until the test clock get a new pending entry"
+          .description = "Wait until the test clock gets a new pending entry.\n"
-            " see #gst_test_clock_wait_for_next_pending_id.",
+            "See #gst_test_clock_wait_for_next_pending_id.",
           .mandatory = FALSE,
           .types = "boolean",
           NULL
@@ -7029,7 +7030,7 @@ register_action_types (void)
         },
         {
           .name = "interpolation-mode",
-          .description = "The name of the GstInterpolationMode to on the source",
+          .description = "The name of the GstInterpolationMode to set on the source",
           .types = "string",
           .mandatory = FALSE,
           .def = "linear",
@@ -7042,10 +7043,12 @@ register_action_types (void)
         },
         {NULL}
       }),
-        "Sets GstTimedValue on pads on elements properties using GstControlBindings \n"
+        "Sets GstTimedValue on pads on elements properties using GstControlBindings\n"
         "and GstControlSource as defined in the parameters.\n"
         "The properties values to set will be defined as:\n\n"
-        "    element-name.padname::property-name=new-value\n\n"
+        "```\n"
+        "element-name.padname::property-name=new-value\n"
+        "```\n\n"
         "> NOTE: `.padname` is not needed if setting a property on an element\n\n"
         "This action also adds necessary control source/control bindings.\n",
       GST_VALIDATE_ACTION_TYPE_NONE);
@@ -7056,7 +7059,9 @@ register_action_types (void)
       }),
         "Check elements and pads properties values.\n"
         "The properties values to check will be defined as:\n\n"
-        "    element-name.padname::property-name\n\n"
+        "```\n"
+        "element-name.padname::property-name\n"
+        "```\n\n"
         "> NOTE: `.padname` is not needed if checking an element property\n\n",
       GST_VALIDATE_ACTION_TYPE_CHECK);
 
@@ -7066,8 +7071,10 @@ register_action_types (void)
       }),
         "Set elements and pads properties values.\n"
         "The properties values to set will be defined as:\n\n"
-        "    element-name.padname::property-name\n\n"
+        "```\n"
-        "> NOTE: `.padname` is not needed if checking an element property\n\n",
+        "    element-name.padname::property-name\n"
+        "```\n\n"
+        "> NOTE: `.padname` is not needed if set an element property\n\n",
       GST_VALIDATE_ACTION_TYPE_NONE);
 
   REGISTER_ACTION_TYPE ("set-property", _execute_set_or_check_property,
@@ -7192,7 +7199,7 @@ register_action_types (void)
         },
         {
           .name = "params",
-          .description = "The signal parametters",
+          .description = "The signal parameters",
           .mandatory = FALSE,
           .types = "ValueArray",
           NULL
@@ -7465,7 +7472,7 @@ register_action_types (void)
            .name = "expected-caps",
            .description = "The expected caps. If not present, expected no caps to be set",
            .mandatory = FALSE,
-           .types = "GstCaps,GstStructure",
+           .types = "caps,structure",
            NULL
         },
         {
@@ -7505,14 +7512,14 @@ register_action_types (void)
         },
         {NULL}
       }),
-      "Check current pipeline position.\n",
+      "Check currently set caps on a particular pad.\n",
       GST_VALIDATE_ACTION_TYPE_NONE | GST_VALIDATE_ACTION_TYPE_CHECK );
 
   REGISTER_ACTION_TYPE("run-command", _run_command,
       ((GstValidateActionParameter[]) {
           {
             .name = "argv",
-            .description = "The subprocess arguments",
+            .description = "The subprocess arguments, include the program name itself",
             .mandatory = TRUE,
             .types = "(string){array,}",
             NULL
@@ -7521,12 +7528,12 @@ register_action_types (void)
             .name = "env",
             .description = "Extra environment variables to set",
             .mandatory = FALSE,
-            .types = "GstStructure",
+            .types = "structure",
             NULL
           },
         {NULL}
       }),
-      "Run external command.\n",
+      "Run an external command.\n",
       GST_VALIDATE_ACTION_TYPE_CAN_BE_OPTIONAL);
 
     REGISTER_ACTION_TYPE("foreach", NULL,
@@ -7534,14 +7541,14 @@ register_action_types (void)
             { .name = "actions",
                 .description = "The array of actions to repeat",
                 .mandatory = TRUE,
-                .types = "strv",
+                .types = "{array of [structures]}",
                 NULL },
             { NULL } }),
         "Run actions defined in the `actions` array the number of times specified\n"
-        " with an iterator parameter passed in. The iterator can be\n"
+        "with an iterator parameter passed in. The iterator can be\n"
-        " a range like :`i=[start, end, step]` or array of values\n"
+        "a range like: `i=[start, end, step]` or array of values\n"
-        " such as: `values=<value1, value2>`.\n"
+        "such as: `values=<value1, value2>`.\n"
-        "One and only iterator field is required as parameter.",
+        "One and only one iterator field is supported as parameter.",
         GST_VALIDATE_ACTION_TYPE_NONE);
     type->prepare = gst_validate_foreach_prepare;