mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2025-01-30 02:58:24 +00:00
validate: doc: Enhance documentation about testfile and meta fields
Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/5803>
This commit is contained in:
Thibault Saunier
GStreamer Marge Bot
parent
a5a65b74ff
commit
a4a97c7568
7 changed files with 207 additions and 74 deletions
|
|
@ -5,7 +5,10 @@
|
|||
``` validate-scenario
|
||||
meta,
|
||||
[allow-errors=(boolean)],
|
||||
[base-time=(double or string (GstClockTime))],
|
||||
[configs=({GstStructure as string})],
|
||||
[duration=(double, int)],
|
||||
[expected-issues=({GstStructure as string})],
|
||||
[handles-states=(boolean)],
|
||||
[ignore-eos=(boolean)],
|
||||
[is-config=(boolean)],
|
||||
|
|
@ -18,10 +21,13 @@ meta,
|
|||
[pipeline-name=(string)],
|
||||
[reverse-playback=(boolean)],
|
||||
[seek=(boolean)],
|
||||
[summary=(string)];
|
||||
[start-time=(double or string (GstClockTime))],
|
||||
[summary=(string)],
|
||||
[use-system-clock=(bool)];
|
||||
```
|
||||
|
||||
Scenario metadata.
|
||||
|
||||
NOTE: it used to be called "description"
|
||||
* Implementer namespace: core
|
||||
* Is config action (meaning it will be executing right at the beginning of the execution of the pipeline)
|
||||
|
|
@ -35,12 +41,76 @@ scenario when it happens. By default a 'stop' action is generated on ERROR messa
|
|||
|
||||
Default: false
|
||||
|
||||
* `base-time`:(optional): The `base-time` fields lets you set the Pipeline base-time as defined in [gst_element_set_base_time](gst_element_set_base_time).
|
||||
|
||||
|
||||
Possible types: `double or string (GstClockTime)`
|
||||
|
||||
Default: None
|
||||
|
||||
* `configs`:(optional): The `configs` field is an array of structures containing the same content as
|
||||
usual [configs](gst-validate-config.md) files.
|
||||
|
||||
For example:
|
||||
|
||||
``` yaml
|
||||
configs = {
|
||||
# Set videotestsrc0 pattern value to `blue`
|
||||
"core, action=set-property, target-element-name=videotestsrc0, property-name=pattern, property-value=blue",
|
||||
"$(validateflow), pad=sink1:sink, caps-properties={ width, height };",
|
||||
}
|
||||
```
|
||||
|
||||
Note: Since this is GstStructure syntax, we need to have the structures in the
|
||||
array as strings/within quotes.
|
||||
|
||||
|
||||
|
||||
Possible types: `{GstStructure as string}`
|
||||
|
||||
Default: {}
|
||||
|
||||
* `duration`:(optional): Lets the user know the time the scenario needs to be fully executed
|
||||
|
||||
Possible types: `double, int`
|
||||
|
||||
Default: infinite (GST_CLOCK_TIME_NONE)
|
||||
|
||||
* `expected-issues`:(optional): The `expected-issues` field is an array of `expected-issue` structures containing
|
||||
information about issues to expect (which can be known bugs or not).
|
||||
|
||||
Use `gst-validate-1.0 --print-issue-types` to print information about all issue types.
|
||||
|
||||
For example:
|
||||
|
||||
``` yaml
|
||||
expected-issues = {
|
||||
"expected-issue, issue-id=scenario::not-ended",
|
||||
}
|
||||
```
|
||||
Note: Since this is GstStructure syntax, we need to have the structures in the
|
||||
array as strings/within quotes.
|
||||
|
||||
**Each issue has the following fields**:
|
||||
|
||||
* `issue-id`: (string): Issue ID - Mandatory if `summary` is not provided.
|
||||
* `summary`: (string): Summary - Mandatory if `issue-id` is not provided.
|
||||
* `details`: Regex string to match the issue details `detected-on`: (string):
|
||||
The name of the element the issue happened on `level`: (string):
|
||||
Issue level
|
||||
* `sometimes`: (boolean): Default: `false` - Wheteher the issue happens only
|
||||
sometimes if `false` and the issue doesn't happen, an error will
|
||||
be issued.
|
||||
* `issue-url`: (string): The url of the issue in the bug tracker if the issue is
|
||||
a bug.
|
||||
|
||||
|
||||
|
||||
|
||||
Possible types: `{GstStructure as string}`
|
||||
|
||||
Default: {}
|
||||
|
||||
* `handles-states`:(optional): Whether the scenario handles pipeline state changes from the beginning
|
||||
in that case the application should not set the state of the pipeline to anything
|
||||
and the scenario action will be executed from the beginning
|
||||
|
|
@ -123,12 +193,26 @@ It has the same effect as setting the pipeline using pipeline_name->scenario_nam
|
|||
|
||||
Default: false
|
||||
|
||||
* `summary`:(optional): Whether the scenario is a config only scenario (ie. explain what it does)
|
||||
* `start-time`:(optional): The `start-time` fields lets you set the Pipeline start-time as defined in [gst_element_set_start_time](gst_element_set_start_time).
|
||||
|
||||
|
||||
Possible types: `double or string (GstClockTime)`
|
||||
|
||||
Default: None
|
||||
|
||||
* `summary`:(optional): A human readable summary of what the test/scenario does
|
||||
|
||||
Possible types: `string`
|
||||
|
||||
Default: 'Nothing'
|
||||
|
||||
* `use-system-clock`:(optional): The `use-system-clock` fields lets you force the Pipeline to use the
|
||||
[`GstSystemClock`](GstSystemClock)
|
||||
|
||||
Possible types: `bool`
|
||||
|
||||
Default: false
|
||||
|
||||
## seek
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -12,9 +12,8 @@ describe the validate [scenario](gst-validate-scenarios.md).
|
|||
|
||||
# The file format
|
||||
|
||||
A validate test file requires a `meta` structure which contains the same
|
||||
information as the [scenario](gst-validate-scenarios.md) `meta` with some
|
||||
additional fields described below. The `meta` structure should be either the
|
||||
A validate test file requires a [`meta`](gst-validate-action-types.md?#meta) structure describing
|
||||
the test and configuring it. The `meta` structure should be either the
|
||||
first or the one following the `set-globals` structure. The `set-globals`
|
||||
structures allows you to set global variables for the rest of the
|
||||
`.validatetest` file and is a free form variables setter. For example you can
|
||||
|
|
@ -40,71 +39,7 @@ args = {
|
|||
}
|
||||
```
|
||||
|
||||
## configs
|
||||
|
||||
The `configs` field is an array of structures containing the same content as
|
||||
usual [configs](gst-validate-config.md) files.
|
||||
|
||||
For example:
|
||||
|
||||
``` yaml
|
||||
configs = {
|
||||
# Set videotestsrc0 pattern value to `blue`
|
||||
"core, action=set-property, target-element-name=videotestsrc0, property-name=pattern, property-value=blue",
|
||||
"$(validateflow), pad=sink1:sink, caps-properties={ width, height };",
|
||||
}
|
||||
```
|
||||
|
||||
Note: Since this is GstStructure synthax, we need to have the structures in the
|
||||
array as strings/within quotes.
|
||||
|
||||
## `base-time`
|
||||
|
||||
The `base-time` fields lets you set the Pipeline base-time as defined in [gst_element_set_base_time](gst_element_set_base_time).
|
||||
|
||||
## `use-system-clock`
|
||||
|
||||
The `use-system-clock` fields lets you set force the Pipeline to use the
|
||||
[`GstSystemClock`](GstSystemClock)
|
||||
|
||||
## `start-time`
|
||||
|
||||
The `start-time` fields lets you set the Pipeline start-time as defined in [gst_element_set_start_time](gst_element_set_start_time).
|
||||
|
||||
## expected-issues
|
||||
|
||||
The `expected-issues` field is an array of `expected-issue` structures containing
|
||||
information about issues to expect (which can be known bugs or not).
|
||||
|
||||
Use `gst-validate-1.0 --print-issue-types` to print information about all issue types.
|
||||
|
||||
For example:
|
||||
|
||||
``` yaml
|
||||
expected-issues = {
|
||||
"expected-issue, issue-id=scenario::not-ended",
|
||||
}
|
||||
```
|
||||
|
||||
Note: Since this is GstStructure synthax, we need to have the structures in the
|
||||
array as strings/within quotes.
|
||||
|
||||
### Fields:
|
||||
|
||||
* `issue-id`: (string): Issue ID - Mandatory if `summary` is not provided.
|
||||
* `summary`: (string): Summary - Mandatory if `issue-id` is not provided.
|
||||
* `details`: Regex string to match the issue details `detected-on`: (string):
|
||||
The name of the element the issue happened on `level`: (string):
|
||||
Issue level
|
||||
* `sometimes`: (boolean): Default: `false` - Wheteher the issue happens only
|
||||
sometimes if `false` and the issue doesn't happen, an error will
|
||||
be issued.
|
||||
* `issue-url`: (string): The url of the issue in the bug tracker if the issue is
|
||||
a bug.
|
||||
|
||||
### Variables
|
||||
|
||||
The same way
|
||||
## Variables
|
||||
|
||||
Validate testfile will define some variables to make those files relocable:
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,17 @@
|
|||
The `configs` field is an array of structures containing the same content as
|
||||
usual [configs](gst-validate-config.md) files.
|
||||
|
||||
For example:
|
||||
|
||||
``` yaml
|
||||
configs = {
|
||||
# Set videotestsrc0 pattern value to `blue`
|
||||
"core, action=set-property, target-element-name=videotestsrc0, property-name=pattern, property-value=blue",
|
||||
"$(validateflow), pad=sink1:sink, caps-properties={ width, height };",
|
||||
}
|
||||
```
|
||||
|
||||
Note: Since this is GstStructure syntax, we need to have the structures in the
|
||||
array as strings/within quotes.
|
||||
|
||||
**Warning**: This field is validate only for [`.validatetest`](gst-validate-test.md) files, and not `.scenario`.
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
The `expected-issues` field is an array of `expected-issue` structures containing
|
||||
information about issues to expect (which can be known bugs or not).
|
||||
|
||||
Use `gst-validate-1.0 --print-issue-types` to print information about all issue types.
|
||||
|
||||
For example:
|
||||
|
||||
``` yaml
|
||||
expected-issues = {
|
||||
"expected-issue, issue-id=scenario::not-ended",
|
||||
}
|
||||
```
|
||||
Note: Since this is GstStructure syntax, we need to have the structures in the
|
||||
array as strings/within quotes.
|
||||
|
||||
**Each issue has the following fields**:
|
||||
|
||||
* `issue-id`: (string): Issue ID - Mandatory if `summary` is not provided.
|
||||
* `summary`: (string): Summary - Mandatory if `issue-id` is not provided.
|
||||
* `details`: Regex string to match the issue details `detected-on`: (string):
|
||||
The name of the element the issue happened on `level`: (string):
|
||||
Issue level
|
||||
* `sometimes`: (boolean): Default: `false` - Wheteher the issue happens only
|
||||
sometimes if `false` and the issue doesn't happen, an error will
|
||||
be issued.
|
||||
* `issue-url`: (string): The url of the issue in the bug tracker if the issue is
|
||||
a bug.
|
||||
|
||||
**Warning**: This field is validate only for [`.validatetest`](gst-validate-test.md) files, and not `.scenario`.
|
||||
|
|
@ -58,6 +58,7 @@
|
|||
#include "gst-validate-utils.h"
|
||||
#include "gst-validate-internal.h"
|
||||
#include "validate.h"
|
||||
#include "validate-resources.h"
|
||||
#include <gst/controller/controller.h>
|
||||
#include <gst/app/app.h>
|
||||
#include <gst/validate/gst-validate-override.h>
|
||||
|
|
@ -7574,12 +7575,21 @@ register_action_types (void)
|
|||
_gst_validate_action_type = gst_validate_action_get_type ();
|
||||
_gst_validate_action_type_type = gst_validate_action_type_get_type ();
|
||||
|
||||
GResource *resource = validate_get_resource ();
|
||||
g_assert (resource);
|
||||
GBytes *meta_config_doc =
|
||||
g_resource_lookup_data (resource, "/validate/doc/meta-configs.md",
|
||||
G_RESOURCE_LOOKUP_FLAGS_NONE, NULL);
|
||||
GBytes *meta_expected_issues_doc =
|
||||
g_resource_lookup_data (resource, "/validate/doc/meta-expected-issues.md",
|
||||
G_RESOURCE_LOOKUP_FLAGS_NONE, NULL);
|
||||
|
||||
/* *INDENT-OFF* */
|
||||
REGISTER_ACTION_TYPE ("meta", NULL,
|
||||
((GstValidateActionParameter []) {
|
||||
{
|
||||
.name = "summary",
|
||||
.description = "Whether the scenario is a config only scenario (ie. explain what it does)",
|
||||
.description = "A human readable summary of what the test/scenario does",
|
||||
.mandatory = FALSE,
|
||||
.types = "string",
|
||||
.possible_variables = NULL,
|
||||
|
|
@ -7708,10 +7718,53 @@ register_action_types (void)
|
|||
.possible_variables = NULL,
|
||||
.def = "false"
|
||||
},
|
||||
{
|
||||
.name = "base-time",
|
||||
.description = "The `base-time` fields lets you set the Pipeline base-time as defined in [gst_element_set_base_time](gst_element_set_base_time).\n",
|
||||
.mandatory = FALSE,
|
||||
.types = "double or string (GstClockTime)",
|
||||
.possible_variables = NULL,
|
||||
.def = "None"
|
||||
},
|
||||
{
|
||||
.name = "start-time",
|
||||
.description = "The `start-time` fields lets you set the Pipeline start-time as defined in [gst_element_set_start_time](gst_element_set_start_time).\n",
|
||||
.mandatory = FALSE,
|
||||
.types = "double or string (GstClockTime)",
|
||||
.possible_variables = NULL,
|
||||
.def = "None"
|
||||
},
|
||||
{
|
||||
.name = "use-system-clock",
|
||||
.description = "The `use-system-clock` fields lets you force the Pipeline to use the\n"
|
||||
"[`GstSystemClock`](GstSystemClock)",
|
||||
.mandatory = FALSE,
|
||||
.types = "bool",
|
||||
.possible_variables = NULL,
|
||||
.def = "false"
|
||||
},
|
||||
{
|
||||
.name="configs",
|
||||
.description=g_bytes_get_data (meta_config_doc, NULL),
|
||||
.mandatory = FALSE,
|
||||
.types = "{GstStructure as string}",
|
||||
.possible_variables = NULL,
|
||||
.def = "{}"
|
||||
},
|
||||
{
|
||||
.name="expected-issues",
|
||||
.description=g_bytes_get_data (meta_expected_issues_doc, NULL),
|
||||
.mandatory = FALSE,
|
||||
.types = "{GstStructure as string}",
|
||||
.possible_variables = NULL,
|
||||
.def = "{}"
|
||||
},
|
||||
{NULL}
|
||||
}),
|
||||
"Scenario metadata.\nNOTE: it used to be called \"description\"",
|
||||
"Scenario metadata.\n\nNOTE: it used to be called \"description\"",
|
||||
GST_VALIDATE_ACTION_TYPE_CONFIG);
|
||||
g_bytes_unref (meta_config_doc);
|
||||
g_bytes_unref (meta_expected_issues_doc);
|
||||
|
||||
REGISTER_ACTION_TYPE ("seek", _execute_seek,
|
||||
((GstValidateActionParameter []) {
|
||||
|
|
|
|||
|
|
@ -56,10 +56,17 @@ gst_validate_enums = gnome.mkenums('gstvalidateenumtypes',
|
|||
install_header : true,
|
||||
install_dir : join_paths(get_option('includedir'), 'gstreamer-1.0/gst/validate'))
|
||||
|
||||
|
||||
validate_resources = gnome.compile_resources(
|
||||
'validate-resources', 'validate.res',
|
||||
source_dir: '.',
|
||||
c_name: 'validate'
|
||||
)
|
||||
|
||||
validate_deps = [gst_check_dep, gst_dep, gst_controller_dep, gstbase_dep, gstapp_dep,
|
||||
gio_dep, gmodule_dep, gst_pbutils_dep, mathlib, json_dep]
|
||||
gstvalidate = library('gstvalidate-@0@'.format(apiversion),
|
||||
sources: gstvalidate_sources + gst_validate_enums + runner_file,
|
||||
sources: gstvalidate_sources + gst_validate_enums + runner_file + validate_resources,
|
||||
version : libversion,
|
||||
soversion : soversion,
|
||||
darwin_versions : osxversion,
|
||||
|
|
@ -70,7 +77,7 @@ gstvalidate = library('gstvalidate-@0@'.format(apiversion),
|
|||
|
||||
if not static_build
|
||||
gstvalidatetracer = library('gstvalidatetracer',
|
||||
sources: gst_validate_enums + runner_file,
|
||||
sources: gst_validate_enums + runner_file + validate_resources,
|
||||
include_directories : [inc_dirs],
|
||||
install: true,
|
||||
c_args : [gst_c_args] + ['-D__GST_VALIDATE_PLUGIN', '-D_GNU_SOURCE', '-DBUILDING_GST_VALIDATE'],
|
||||
|
|
|
|||
|
|
@ -0,0 +1,8 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<gresources>
|
||||
<gresource prefix="/validate/">
|
||||
<file>doc/meta-configs.md</file>
|
||||
<file>doc/meta-expected-issues.md</file>
|
||||
</gresource>
|
||||
</gresources>
|
||||
|
||||
Loading…
Reference in a new issue