docs/gst-validate-launcher.md

   1 ---
   2 short-description: Integration testsuite builder and launcher
   3 ...
   4
   5 # gst-validate-launcher
   6
   7 `gst-validate-launcher` is an application to create full testsuites on
   8 top of the GstValidate tools, testing behaviour with dynamic pipelines
   9 and user actions (seeking, changing the pipeline state, etc.) as
  10 described by the [scenario](GstValidateScenario) format.
  11
  12 ## Run the GstValidate default testsuite
  13
  14 GstValidate comes with a default testsuite to be executed on a default
  15 set of media samples. Those media samples are stored with `git-annex` so
  16 you will need it to be able to launch the default testsuite.
  17
  18 The first time you launch the testsuite, you will need to make sure that
  19 the media samples are downloaded. To do so and launch the testsuite you
  20 can simply do:
  21
  22     gst-validate-launcher validate --sync
  23
  24 This will only launch the GstValidate tests and not other applications
  25 that might be supported (currently `ges-launch` is also supported and
  26 has its own default testsuite).
  27
  28 Launching the default testsuite will open/close many windows, you might
  29 want to mute it so you can keep using your computer:
  30
  31     gst-validate-launcher validate --sync --mute
  32
  33 ## Example of a testsuite implementation
  34
  35 To implement a testsuite, you will have to write some simple python code
  36 that defines the tests to be launched by `gst-validate-launcher`.
  37
  38 In this example, we will assume that you want to write a whole new
  39 testsuite based on your own media samples and [scenarios](GstValidateScenario). The
  40 set of media files and the testsuite implementation file will be
  41 structured as follow:
  42
  43     testsuite_folder/
  44       |-> testsuite.py
  45       |-> sample_files/
  46           |-> file.mp4
  47           |-> file1.mkv
  48           |-> file2.ogv
  49       |-> scenarios
  50           |-> scenario.scenario
  51           |-> scenario1.scenario
  52
  53 You should generate the `.media_info` files. To generate them for local
  54 files, you can use:
  55
  56     gst-validate-launcher --medias-paths /path/to/sample_files/ --generate-media-info
  57
  58 For remote streams, you should use
  59 `gst-validate-media-check-GST_API_VERSION`. For an http stream you can
  60 for example do:
  61
  62     gst-validate-media-check-GST_API_VERSION http://someonlinestream.com/thestream \
  63                   --output-file /path/to/testsuite_folder/sample_files/thestream.stream_info
  64
  65
  66 The `gst-validate-launcher` will use the generated `.media_info` and
  67 `.stream_info` files to validate the tests as those contain the
  68 necessary information.
  69
  70 Then you will need to write the `testsuite.py` file. You can for example
  71 implement the following testsuite:
  72
  73 ``` python
  74 import os
  75
  76 # Make sure gst-validate-launcher uses our media files
  77 options.paths = os.path.dirname(os.path.realpath(__file__))
  78
  79 # Make sure GstValidate is able to use our scenarios
  80 # from the testsuite_folder/scenarios folder
  81 os.environ["GST_VALIDATE_SCENARIOS_PATH"] = \
  82     os.path.join(os.path.dirname(os.path.realpath(__file__)), "scenarios")
  83
  84 # You can activate the following if you only care about critical issues in
  85 # the report:
  86 # os.environ["GST_VALIDATE"] = "print_criticals"
  87
  88 # Make gst-validate use our scenarios
  89 validate.add_scenarios(["scenario", "scenario1"])
  90
  91
  92 # Now add "Theora and Vorbis in OGG container" as a wanted transcoding format. That means
  93 # that conversion to this format will be tested on all the media files/streams.
  94 validate.add_encoding_formats([MediaFormatCombination("ogg", "vorbis", "theora")])
  95
  96 # Use the GstValidatePlaybinTestsGenerator to generate tests that will use playbin
  97 # and GstValidateTranscodingTestsGenerator to create media transcoding tests that
  98 # will use all the media format added with validate.add_encoding_formats
  99 validate.add_generators([validate.GstValidatePlaybinTestsGenerator(validate),
 100                          GstValidateTranscodingTestsGenerator(self)])
 101
 102 # Blacklist some tests that are known to fail because a feature is not supported
 103 # or due to any other reason.
 104 # The tuple defining those tests is of the form:
 105 # ("regex defining the test name", "Reason why the test should be disabled")
 106 validate.set_default_blacklist([
 107         ("validate.*.scenario1.*ogv$"
 108          "oggdemux does not support some action executed in scenario1")]
 109         )
 110 ```
 111
 112 Once this is done, you've got a testsuite that will:
 113
 114 -   Run playbin pipelines on `file.mp4`, `file1.mkv` and `file2.ogv`&gt;
 115     executing `scenario` and `scenario1` scenarios
 116
 117 -   Transcode `file.mp4,` `file1.mkv` and `file2.ogv` to Theora and
 118     Vorbis in a OGG container
 119
 120 The only thing to do to run the testsuite is:
 121
 122
 123     gst-validate-launcher --config /path/to/testsuite_folder/testsuite.py
 124
 125 # Invocation
 126
 127 You can find detailed information about the launcher by launching it:
 128
 129     gst-validate-launcher --help