validate: Update action types documentation

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/3040>
This commit is contained in:
Thibault Saunier 2022-09-16 22:05:18 -03:00 committed by GStreamer Marge Bot
parent b6ca76eb68
commit ec291ce6bb
2 changed files with 409 additions and 88 deletions

View file

@ -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
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.
* `playback-time`:(optional): The playback time at which the action will be executed
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
Possible types: `string`
Default: src
* `target-element-factory-name`:(optional): The factory name of the GstElements 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
on whatever happens first.
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

View file

@ -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 "
"a 'stop' action is generated one ERROR messages",
.description = "Ignore error messages and keep executing the\n"
"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"
" see #gst_test_clock_wait_for_next_pending_id.",
.description = "Wait until the test clock gets a new pending entry.\n"
"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",
@ -7045,7 +7046,9 @@ register_action_types (void)
"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"
"> NOTE: `.padname` is not needed if checking an element property\n\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"
"a range like: `i=[start, end, step]` or array of values\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;