diff --git a/subprojects/gst-devtools/docs/gst-validate-action-types.md b/subprojects/gst-devtools/docs/gst-validate-action-types.md index 0837bfc60b..0d435b6f07 100644 --- a/subprojects/gst-devtools/docs/gst-validate-action-types.md +++ b/subprojects/gst-devtools/docs/gst-validate-action-types.md @@ -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 diff --git a/subprojects/gst-devtools/docs/gst-validate-test-file.md b/subprojects/gst-devtools/docs/gst-validate-test-file.md index 9e6a5c3625..3b9c798944 100644 --- a/subprojects/gst-devtools/docs/gst-validate-test-file.md +++ b/subprojects/gst-devtools/docs/gst-validate-test-file.md @@ -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: diff --git a/subprojects/gst-devtools/validate/gst/validate/doc/meta-configs.md b/subprojects/gst-devtools/validate/gst/validate/doc/meta-configs.md new file mode 100644 index 0000000000..c87d8c472a --- /dev/null +++ b/subprojects/gst-devtools/validate/gst/validate/doc/meta-configs.md @@ -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`. diff --git a/subprojects/gst-devtools/validate/gst/validate/doc/meta-expected-issues.md b/subprojects/gst-devtools/validate/gst/validate/doc/meta-expected-issues.md new file mode 100644 index 0000000000..965fe5cf5f --- /dev/null +++ b/subprojects/gst-devtools/validate/gst/validate/doc/meta-expected-issues.md @@ -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`. diff --git a/subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c b/subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c index 289f35dc45..8049f44d64 100644 --- a/subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c +++ b/subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c @@ -58,6 +58,7 @@ #include "gst-validate-utils.h" #include "gst-validate-internal.h" #include "validate.h" +#include "validate-resources.h" #include #include #include @@ -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 []) { diff --git a/subprojects/gst-devtools/validate/gst/validate/meson.build b/subprojects/gst-devtools/validate/gst/validate/meson.build index 45347444e1..6954497906 100644 --- a/subprojects/gst-devtools/validate/gst/validate/meson.build +++ b/subprojects/gst-devtools/validate/gst/validate/meson.build @@ -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'], diff --git a/subprojects/gst-devtools/validate/gst/validate/validate.res b/subprojects/gst-devtools/validate/gst/validate/validate.res new file mode 100644 index 0000000000..1568b88d40 --- /dev/null +++ b/subprojects/gst-devtools/validate/gst/validate/validate.res @@ -0,0 +1,8 @@ + + + + doc/meta-configs.md + doc/meta-expected-issues.md + + +