<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<section id="media-source-testing-plugins">
<title>Testing your plugins</title>
<para>
Grilo ships a GTK+ test user interface called <emphasis>grilo-test-ui</emphasis>
that can be used to test new plugins. This simple playground application can be
found in the 'grilo' core source code under tools/grilo-test-ui/. If you have
Grilo installed on your system, you may have this application installed as
well.
</para>
<para>
This application loads plugins from the default plugin installation directory
in your system or, alternatively, by inspecting the GRL_PLUGIN_PATH environment
variable, which can be set to contain a list of directories where Grilo
should look for plugins.
</para>
<para>
Once the plugin library is visible to Grilo one only has to start the
grilo-test-ui application and it will load it along with other Grilo
plugins available in the system.
</para>
<para>
In case there is some problem with the initialization of the plugin it should
be logged on the console. Remember that you can control the amount of
logging done by Grilo through the GRL_DEBUG environment variable. You
may want to set this variable to do full logging, in which case
you should type this in your console:
</para>
<programlisting>
$ export GRL_DEBUG="*:*"
</programlisting>
<para>
If you want to focus only on logging the plugin loading process, configure
Grilo to log full details from the plugin registry module alone
by doing this instead:
</para>
<programlisting>
$ export GRL_DEBUG="registry:*"
</programlisting>
<para>
In case your plugin has been loaded successfully you should see something like
this in the log:
</para>
<programlisting>
(lt-grilo-test-ui:14457): Grilo-DEBUG: [registry] grl-registry.c:188: Plugin rank [plugin-id]' : 0
(lt-grilo-test-ui:14457): Grilo-DEBUG: [registry] grl-registry.c:476: New source available: [source-id]
(lt-grilo-test-ui:14457): Grilo-DEBUG: [registry] grl-registry.c:683: Loaded plugin '[plugin-id]' from '[plugin-file-absolute-path.so]'
</programlisting>
<para>
If your plugin is a Media Source (not a Metadata Source) you should be able
to see it in the user interface of grilo-test-ui like this:
<itemizedlist>
<listitem>
If the plugin implements Browse you should see the media source objects
spawned by the plugin in the list shown in the main view. You can
browse the plugin by double-clicking on any of its sources.
</listitem>
<listitem>
If the plugin implements Search you should see the media source objects
spawned by the plugin in the combo box next to the "Search" button.
You can now search content by selecting the media source you want to test
in the combo, inputting a search text in the text entry right next to it
and clicking the Search button.
</listitem>
<listitem>
If the plugin implements query you should see the media source objects
spawned by the plugin in the combo box next to the "Query" button.
You can now query content by selecting the media source you want to test
in the combo, inputting the plugin-specific query string in the text
entry right next to it and clicking the Query button.
</listitem>
</itemizedlist>
</para>
<para>
If your plugin is a Metadata Source then you should test it by doing
a Browse, Search or Query operation in some other Media Source available
and then click on any of the media items showed as result. By doing this
grilo-test-ui will execute a Metadata operation which would use any
available metadata plugins to gather as much information as possible.
Available metadata obtained for the selected item will be shown in the
right pane for users to inspect.
</para>
<section>
<title>Simulating Network Replies</title>
<para>
For offline testing of plug-ins, particularly in automated tests, it is
useful to simulate and return predefined network replies. Therefore, Grilo
provides a few facilities for mocking network replies.
</para>
<para>
To enable mocking, set the environment variable GRL_NET_MOCKED. The value
of this variable is interpreted as the path of the mock configuration file to
use. This file is a simple .ini file, split
into a "default" section and one section per URL to mock.
</para>
<programlisting>
[default]
version = 1
ignored-parameters = field1[;field2[;...]] or "*"
[http://www.example.com]
data = content/of/response.txt
timeout = 500
</programlisting>
<para>
An easy way to capture the responses is to run your application with the
environment variable GRL_NET_CAPTURE_DIR. GrlNetWc will then write
each response into a file following the pattern "url-timestamp". If the
directory does not exist yet then it will be created.
</para>
<section>
<title>The Default Section</title>
<para>
This section needs to be present in any mock reply configuration file.
<itemizedlist>
<listitem>
<varname>version</varname> needs to be "1".
</listitem>
<listitem>
<varname>ignored-parameters</varname> is a semicolon separated list of
query parameter names that can be used to map URLs to sections
without paying attention to query parameters listed here.
By setting a value of "api_key" a request for
<code>http://www.example.com?q=test+query&api_key=dummy</code>
will be answered with the mock data for
<code>http://www.example.com?q=test+query</code>.
Setting "api_key;q" or "*" will result in mock answer for
<code>http://www.example.com</code>.
</listitem>
</itemizedlist>
</para>
</section>
<section>
<title>The URL Sections</title>
<para>
The section title is used to map URLs to response files.
<itemizedlist>
<listitem>
<varname>data</varname> is a path to a text file containing the
raw response of the websserver. The path may be relative to this
configuration file or an absolute path.
</listitem>
<listitem>
<varname>timeout</varname> may be used to delay the response in
seconds. The default is to not delay at all.
</listitem>
</itemizedlist>
Skip the <varname>data</varname> field to provoke a "not found" error.
</para>
</section>
</section>
</section>