[retro-gtk] doc: Add the Retro Reference Test Case Specification 1.0 section



commit f2d65e3864e85f450d77d9c52e723381f95820e4
Author: Adrien Plazas <kekun plazas laposte net>
Date:   Sat Oct 17 20:51:03 2020 +0200

    doc: Add the Retro Reference Test Case Specification 1.0 section
    
    This is a port of the Retro Reference Test Case Specification 1.0 from
    https://wiki.gnome.org/Apps/Games/Documentation/RetroReftest, as having
    it within the retro-gtk documentation makes more sense.

 doc/meson.build             |   1 +
 doc/reference-test-case.xml | 244 ++++++++++++++++++++++++++++++++++++++++++++
 doc/retro-gtk-doc.xml       |   1 +
 3 files changed, 246 insertions(+)
---
diff --git a/doc/meson.build b/doc/meson.build
index 330296d9..0c0f7c84 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -27,6 +27,7 @@ private_headers = [
 
 content_files = [
   'libretro-core-descriptor.xml',
+  'reference-test-case.xml',
 ]
 
 gnome.gtkdoc(
diff --git a/doc/reference-test-case.xml b/doc/reference-test-case.xml
new file mode 100644
index 00000000..7f980e56
--- /dev/null
+++ b/doc/reference-test-case.xml
@@ -0,0 +1,244 @@
+<?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'">
+  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+  %gtkdocentities;
+]>
+
+<refentry id="reference-test-case">
+  <refmeta>
+    <refentrytitle>Retro Reference Test Case Specification 1.0</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv/>
+
+  <refsect2>
+    <title>Introduction</title>
+
+    <para>
+      This is the first version of the reference test case specification used by
+      <literal>retro-reftest</literal>.
+      These test cases will run a series of interdependent smaller tests on a
+      Libretro core to ensure it behaves as expected.
+    </para>
+  </refsect2>
+
+  <refsect2>
+    <title>The Tests</title>
+
+    <para>
+      The tests are based on
+      <ulink url="https://developer.gnome.org/glib/stable/glib-Testing.html";>the Glib test framework</ulink>,
+      as such they must have a path describing the test which will be used as
+      the root for all the tests it runs.
+    </para>
+
+    <para>
+      First, the fllowing tests will be run in this order:
+      <itemizedlist>
+        <listitem>
+          <literal>Boot</literal>: Tests loading the core with the optional
+          medias and booting it.
+        </listitem>
+        <listitem>
+          <literal>Options</literal>: If options are specified, tests that the
+          ones offered by the core are as expected.
+        </listitem>
+      </itemizedlist>
+    </para>
+
+    <para>
+      Then the following tests will be run on specific frames:
+      <itemizedlist>
+        <listitem>
+          <literal>FastForward</literal>: If there is a gap between the last ran
+          frame and the frame to run, quickly run all the inbetween frames.
+        </listitem>
+        <listitem>
+          One of the following state tests can be run:
+          <itemizedlist>
+            <listitem>
+              <literal>State None</literal>: If specified, will test that no state
+              can be accessed.
+            </listitem>
+            <listitem>
+              <literal>State Refresh</literal>: If specified, will test that the
+              sate can be accessed by saving and instantaneously reloading it.
+            </listitem>
+          </itemizedlist>
+        </listitem>
+        <listitem>
+          <literal>Run</literal>: Will run the frame.
+        </listitem>
+        <listitem>
+          <literal>Video</literal>: If specified, will test that the video
+          output is as expected.
+        </listitem>
+      </itemizedlist>
+    </para>
+
+  </refsect2>
+
+  <refsect2>
+    <title>Basic Format of the File</title>
+
+    <para>
+      The basic format of the file is the same as the
+      <ulink url="https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s02.html";>Freedesktop 
desktop entries</ulink>,
+      which is implemented in the Glib as
+      <ulink url="https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html";>GKeyFile</ulink>.
+    </para>
+  </refsect2>
+
+  <refsect2>
+    <title>Recognized Keys</title>
+
+    <refsect3>
+      <title>Retro Reftest</title>
+
+      <para>
+        <table>
+          <thead>
+            <tr>
+              <td>Key</td>
+              <td>Value Type</td>
+              <td>Required</td>
+              <td>Description</td>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>Path</td>
+              <td>string</td>
+              <td>Yes</td>
+              <td>The test path as understood by <ulink 
url="https://developer.gnome.org/glib/stable/glib-Testing.html";>the Glib test framework</ulink> to be used as 
the root for the test paths of this test case.</td>
+            </tr>
+            <tr>
+              <td>Core</td>
+              <td>string</td>
+              <td>Yes</td>
+              <td>The path (absolute or relative to this file's location) to the Libretro core's module.</td>
+            </tr>
+            <tr>
+              <td>Medias</td>
+              <td>string(s)</td>
+              <td>No</td>
+              <td>A list of media paths (absolute or relative to this file's location) to be loaded by the 
core.</td>
+            </tr>
+          </tbody>
+        </table>
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Options</title>
+
+      <para>
+        If this group is present, the <literal>Options</literal> test will be
+        added.
+        This group lists the expected options set by the tested Libretro core
+        via <literal>RETRO_ENVIRONMENT_SET_VARIABLES</literal>, the keys
+        correspond to these options’ keys and the values are string lists
+        listing the available values. To check that the core has no option, add
+        an empty <literal>Options</literal> group.
+      </para>
+    </refsect3>
+
+    <refsect3>
+      <title>Frames</title>
+
+      <para>
+        <table>
+          <thead>
+            <tr>
+              <td>Key</td>
+              <td>Value Type</td>
+              <td>Required</td>
+              <td>Description</td>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>State</td>
+              <td>string</td>
+              <td>No</td>
+              <td>One of <literal>None</literal> or <literal>Refresh</literal>.</td>
+            </tr>
+            <tr>
+              <td>Video</td>
+              <td>string</td>
+              <td>No</td>
+              <td>The path (absolute or relative to this file's location) to the expected video output 
image.</td>
+            </tr>
+          </tbody>
+        </table>
+      </para>
+    </refsect3>
+  </refsect2>
+
+  <refsect2>
+    <title>Example</title>
+
+    <para>
+      An example test case for a test core and its expected output:
+      <informalexample><programlisting>
+        [Retro Reftest]
+        Path=/test
+        Core=/app/lib/libretro/test_libretro.so
+
+        [Options]
+        test_aspect=4:3;16:9;
+        test_samplerate=30000;20000;
+        test_opt0=false;true;
+        test_opt1=0;
+        test_opt2=0;1;foo;3;
+
+        [Frame 0]
+        State=Refresh
+        Video=test.png
+      </programlisting></informalexample>
+    </para>
+    <para>
+      <informalexample><programlisting>
+        /test/Boot: OK
+        /test/Options: OK
+        /test/0/State Refresh: OK
+        /test/0/Run: OK
+        /test/0/Video: OK
+      </programlisting></informalexample>
+    </para>
+
+    <para>
+      An example test case for a Sega Genesis emulator and its expected output:
+      <informalexample><programlisting>
+        [Retro Reftest]
+        Path=/blastem/240pSuite
+        Core=/app/lib/libretro/blastem_libretro.so
+        Medias=240pTestSuite-v15.gen;
+
+        [Frame 150]
+        Video=blastem.240pSuite.150.png
+      </programlisting></informalexample>
+    </para>
+    <para>
+      <informalexample><programlisting>
+        /blastem/240pSuite/Boot: OK
+        /blastem/240pSuite/150/FastForward: OK
+        /blastem/240pSuite/150/Run: OK
+        /blastem/240pSuite/150/Video: OK
+      </programlisting></informalexample>
+    </para>
+  </refsect2>
+
+  <refsect2>
+    <title>References</title>
+
+    <para>
+      <itemizedlist>
+        <listitem><ulink url="https://specifications.freedesktop.org/desktop-entry-spec/latest/";>The desktop 
entry specification</ulink></listitem>
+      </itemizedlist>
+    </para>
+  </refsect2>
+</refentry>
diff --git a/doc/retro-gtk-doc.xml b/doc/retro-gtk-doc.xml
index 192f9b0a..96b8e92f 100644
--- a/doc/retro-gtk-doc.xml
+++ b/doc/retro-gtk-doc.xml
@@ -32,6 +32,7 @@
     <title>RetroGTK Overview</title>
 
     <xi:include href="libretro-core-descriptor.xml"/>
+    <xi:include href="reference-test-case.xml"/>
   </chapter>
 
   <chapter id="core-api">


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]