example_run() function: test the examples of the help pages 08/6608/14
Vincent COUVERT [Tue, 6 Mar 2012 16:03:03 +0000 (17:03 +0100)]
To test:
 - example_run("core")
 - example_run("core", "argn")
 - example_run("core", ["argn"; "mode"])
 - example_run("core", "argn", "en_US")
 - example_run("xml", [], "en_US", "no_check_error_output")

Change-Id: I474cd05344d2eed9dfe893604fdc2862b82bf654

SEP/INDEX
SEP/SEP_083_example_run.odt [new file with mode: 0644]
scilab/CHANGES_5.4.X
scilab/modules/development_tools/help/en_US/example_run.xml [new file with mode: 0644]
scilab/modules/development_tools/macros/example_run.sci [new file with mode: 0644]
scilab/modules/development_tools/tests/unit_tests/example_run.dia.ref [new file with mode: 0644]
scilab/modules/development_tools/tests/unit_tests/example_run.tst [new file with mode: 0644]

index 49f09f7..2dab397 100644 (file)
--- a/SEP/INDEX
+++ b/SEP/INDEX
@@ -81,4 +81,4 @@ SEP #081: new argument for test_run to generate a xunit report
 SEP #082: eigs function
 SEP #083: example_run function
 SEP #084: fft improvements
-SEP #085: conv improvements
\ No newline at end of file
+SEP #085: conv improvements
diff --git a/SEP/SEP_083_example_run.odt b/SEP/SEP_083_example_run.odt
new file mode 100644 (file)
index 0000000..bc94740
Binary files /dev/null and b/SEP/SEP_083_example_run.odt differ
index 035150a..a85a6d7 100644 (file)
@@ -93,6 +93,9 @@ Unitary tests
 
 * A fourth argument added to test_run to export test results to XUnit format.
 
+* A new function called example_run has been introduced, this function tests the
+  examples given in Scilab help pages. See SEP #83.
+
 
 Statistics
 ==========
diff --git a/scilab/modules/development_tools/help/en_US/example_run.xml b/scilab/modules/development_tools/help/en_US/example_run.xml
new file mode 100644 (file)
index 0000000..2d2937c
--- /dev/null
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2012 - Scilab Enterprises - Vincent COUVERT
+ *
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="example_run" xml:lang="en">
+  <refnamediv>
+    <refname>example_run</refname>
+    <refpurpose>Launch the examples found in help pages.</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+    <synopsis>
+      example_run()
+      example_run(moduleNames)
+      example_run(moduleNames, functionNames)
+      example_run(moduleNames, functionNames, language)
+      example_run(moduleNames, functionNames, language, testrunOptions, testrunExportToFile)
+    </synopsis>
+  </refsynopsisdiv>
+  <refsection>
+    <title>Arguments</title>
+    <variablelist>
+      <varlistentry>
+        <term>moduleNames</term>
+        <listitem>
+          <para>
+            a string or a string vector: the name(s) of the modules to test. Default value is the value returned by <link linkend="getmodules">getmodules()</link>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>functionNames</term>
+        <listitem>
+          <para>a string or a string vector: the name(s) of the functions to test. If not given, all help pages of the module(s) will be tested.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>language</term>
+        <listitem>
+          <para>a string: the language of the help pages to test. Default value is "en_US".</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>testrunOptions</term>
+        <listitem>
+          <para>
+            Used as third input argument for <link linkend="test_run">test_run</link>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>testrunExportToFile</term>
+        <listitem>
+          <para>
+            Used as forth input argument for <link linkend="test_run">test_run</link>.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+  <refsection>
+    <title>Description</title>
+    <para>
+      This function extracts the examples given in help pages and run them using <link linkend="test_run">test_run</link>.
+    </para>
+  </refsection>
+  <refsection>
+    <title>Example</title>
+    <programlisting role="example"><![CDATA[
+example_run("core")
+example_run("core", "argn")
+example_run("core", ["argn"; "mode"])
+example_run("core", "argn", "en_US")
+ ]]></programlisting>
+  </refsection>
+  <refsection role="see also">
+    <title>See Also</title>
+    <simplelist type="inline">
+      <member>
+        <link linkend="test_run">test_run</link>
+      </member>
+    </simplelist>
+  </refsection>
+  <refsection>
+    <title>History</title>
+    <revhistory>
+      <revision>
+        <revnumber>5.4.0</revnumber>
+        <revremark>Function example_run introduced.</revremark>
+      </revision>
+    </revhistory>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/development_tools/macros/example_run.sci b/scilab/modules/development_tools/macros/example_run.sci
new file mode 100644 (file)
index 0000000..82ac35d
--- /dev/null
@@ -0,0 +1,157 @@
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+// Copyright (C) 2012 - Scilab Enterprises - Vincent COUVERT
+//
+// This file must be used under the terms of the CeCILL.
+// This source file is licensed as described in the file COPYING, which
+// you should have received as part of this distribution.  The terms
+// are also available at
+// http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+
+function boolStatus = example_run(modulesName, functionsName, helpLanguage, varargin)
+
+    rhs = argn(2);
+
+    if rhs < 1 then
+        modulesName = getmodules();
+    end
+    if rhs < 2 then
+        functionsName = [];
+    end
+    if rhs < 3 then
+        helpLanguage = "en_US";
+    end
+
+    if typeof(modulesName)<>"string" then
+        error(msprintf(gettext("%s: Wrong type for input argument #%d: A row array of strings expected.\n"), "example_run", 1));
+    end
+    if size(modulesName, 2)<>1 then
+        error(msprintf(gettext("%s: Wrong size for input argument #%d: A row array of strings expected.\n"), "example_run", 1));
+    end
+
+    if (typeof(functionsName)=="constant" & ~isempty(functionsName)) & typeof(functionsName)<>"string" then
+        error(msprintf(gettext("%s: Wrong type for input argument #%d: A row array of strings or empty matrix expected.\n"), "example_run", 2));
+    end
+    if ~isempty(functionsName) & size(functionsName, 2)<>1 then
+        error(msprintf(gettext("%s: Wrong size for input argument #%d: A row array of strings or empty matrix expected.\n"), "example_run", 2));
+    end
+
+    if typeof(helpLanguage)<>"string" then
+        error(msprintf(gettext("%s: Wrong type for input argument #%d: A string expected.\n"), "example_run", 3));
+    end
+    if size(helpLanguage, "*")<>1 then
+        error(msprintf(gettext("%s: Wrong size for input argument #%d: A string expected.\n"), "example_run", 3));
+    end
+
+    for kMod = 1:size(modulesName, "*")
+
+        moduleName = modulesName(kMod);
+
+        moduleDir = SCI + filesep() + "modules" + filesep() + moduleName + filesep() + "help" + filesep();
+        if ~isdir(moduleDir) then
+            error(msprintf(gettext("%s: Wrong value for input argument #%d: A Scilab module name expected.\n"), "example_run", 1));
+            return
+        end
+
+        moduleDir = moduleDir + helpLanguage + filesep();
+        if ~isdir(moduleDir) then
+            error(msprintf(gettext("%s: Wrong value for input argument #%d: A valid language expected.\n"), "example_run", 3));
+            return
+        end
+
+        tempModuleName = moduleName + "_help";
+
+        workDir = TMPDIR + filesep() + tempModuleName + filesep() + "tests" + filesep() + "unit_tests" + filesep();
+        if isdir(workDir) then
+            rmdir(workDir, "s");
+        end
+
+        if isempty(functionsName) then
+            xmlFiles = findHelpFiles(moduleDir, []);
+
+            for kFile = 1:size(xmlFiles, "*")
+                xmlFile = xmlFiles(kFile);
+                createTestsFromHelp(moduleDir, workDir, xmlFile)
+            end
+        else
+            for kFunction = 1:size(functionsName, "*")
+                xmlFiles = findHelpFiles(moduleDir, functionsName(kFunction));
+                if isempty(xmlFiles) then // The user wants to test a specific file
+                    error(msprintf(gettext("%s: Wrong value for input argument #%d: A ''%s'' module function name expected.\n"), "example_run", 2, moduleName));
+                    return
+                end
+
+                for kFile = 1:size(xmlFiles, "*")
+                    xmlFile = xmlFiles(kFile);
+                    createTestsFromHelp(moduleDir, workDir, xmlFile)
+                end
+            end
+        end
+
+        if rhs > 3 then
+            boolStatus = test_run(TMPDIR +  filesep() + tempModuleName, [], varargin(:))
+        else
+            boolStatus = test_run(TMPDIR +  filesep() + tempModuleName, [])
+        end
+    end
+
+endfunction
+
+function createTestsFromHelp(baseDirectory, outputDirectory, helpFile)
+
+    mkdir(outputDirectory);
+
+    helpFileDoc = xmlRead(helpFile);
+
+    // Find all programlisting tag in the file
+    exampleTags = xmlXPath(helpFileDoc, "//scilabhelpfile:programlisting", ["scilabhelpfile" "http://docbook.org/ns/docbook"]);
+
+    for kExample = 1:size(exampleTags, "*")
+
+        programListing = [];
+
+        if exampleTags(kExample).attributes.role == "interactive-example" then
+            programListing = ["// <-- INTERACTIVE TEST -->" ; programListing];
+        end
+
+        ignoredRoles = ["no-scilab-exec"];
+        ignoreExample = or(exampleTags(kExample).attributes.role==ignoredRoles) | isempty(exampleTags(kExample).attributes.role);
+
+        programListing = ["// <-- NO CHECK REF -->" ; programListing; exampleTags(kExample).content];
+
+        if ~ignoreExample then
+            functionName = fileparts(helpFile, "fname");
+            relPath = dirname(getrelativefilename(baseDirectory, helpFile));
+
+            mkdir(outputDirectory + relPath + filesep())
+
+            if size(exampleTags, "*")>1 then
+                mputl(programListing, outputDirectory + relPath + filesep() + functionName + "_" + string(kExample) + ".tst");
+            else
+                mputl(programListing, outputDirectory + relPath + filesep() + functionName + ".tst");
+            end
+        end
+    end
+
+endfunction
+
+function xmlFilenames = findHelpFiles(directory, functionName)
+
+    xmlFilenames = [];
+
+    allFiles = ls(directory);
+
+    for kFile = 1:size(allFiles, "*")
+        if isfile(allFiles(kFile)) then
+            if fileparts(allFiles(kFile), "extension")==".xml" then
+                if isempty(functionName) then
+                    xmlFilenames($+1) = allFiles(kFile);
+                elseif fileparts(allFiles(kFile), "fname")==functionName then
+                    xmlFilenames($+1) = allFiles(kFile);
+                end
+            end
+        else // Directory
+            xmlFilenames = [xmlFilenames;findHelpFiles(directory + allFiles(kFile) + filesep(), functionName)]
+        end
+    end
+
+endfunction
diff --git a/scilab/modules/development_tools/tests/unit_tests/example_run.dia.ref b/scilab/modules/development_tools/tests/unit_tests/example_run.dia.ref
new file mode 100644 (file)
index 0000000..0d05135
--- /dev/null
@@ -0,0 +1,160 @@
+// =============================================================================
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+// Copyright (C) 2012 - Scilab Enterprises - Vincent COUVERT
+//
+//  This file is distributed under the same license as the Scilab package.
+// =============================================================================
+// <-- CLI SHELL MODE -->
+// Test errors
+refMsg = msprintf(gettext("%s: Wrong type for input argument #%d: A row array of strings expected.\n"), "example_run", 1);
+assert_checkerror("example_run(10);", refMsg);
+refMsg = msprintf(gettext("%s: Wrong size for input argument #%d: A row array of strings expected.\n"), "example_run", 1);
+assert_checkerror("example_run([""core"",""xml""]);", refMsg);
+refMsg = msprintf(gettext("%s: Wrong type for input argument #%d: A row array of strings or empty matrix expected.\n"), "example_run", 2);
+assert_checkerror("example_run(""core"", 12);", refMsg);
+refMsg = msprintf(gettext("%s: Wrong size for input argument #%d: A row array of strings or empty matrix expected.\n"), "example_run", 2);
+assert_checkerror("example_run(""core"", [""argn"", ""insertion""]);", refMsg);
+refMsg = msprintf(gettext("%s: Wrong type for input argument #%d: A string expected.\n"), "example_run", 3);
+assert_checkerror("example_run(""core"", ""argn"", 12);", refMsg);
+refMsg = msprintf(gettext("%s: Wrong size for input argument #%d: A string expected.\n"), "example_run", 3);
+assert_checkerror("example_run(""core"", ""argn"", [""en_US"", ""fr_FR""]);", refMsg);
+refMsg = msprintf(gettext("%s: Wrong value for input argument #%d: A Scilab module name expected.\n"), "example_run", 1);
+assert_checkerror("example_run(""toto"");", refMsg);
+refMsg = msprintf(gettext("%s: Wrong value for input argument #%d: A ''%s'' module function name expected.\n"), "example_run", 2, "core");
+assert_checkerror("example_run(""core"", ""doesnotexistsname"");", refMsg);
+refMsg = msprintf(gettext("%s: Wrong value for input argument #%d: A valid language expected.\n"), "example_run", 3);
+assert_checkerror("example_run(""core"", ""argn"", ""aa_BB"");", refMsg);
+example_run("xml");
+   TMPDIR = TMPDIR
+
+   001/001 - [TMPDIR/xml_help] : 
+
+   001/030 - [TMPDIR/xml_help] XMLObjects_1..passed
+   002/030 - [TMPDIR/xml_help] XMLObjects_2..passed
+   003/030 - [TMPDIR/xml_help] XMLObjects_3..passed
+   004/030 - [TMPDIR/xml_help] XMLObjects_4..passed
+   005/030 - [TMPDIR/xml_help] XMLObjects_5..passed
+   006/030 - [TMPDIR/xml_help] XMLObjects_6..passed
+   007/030 - [TMPDIR/xml_help] XMLObjects_7..passed
+   008/030 - [TMPDIR/xml_help] xmlAddNs......passed
+   009/030 - [TMPDIR/xml_help] xmlAsNumber...passed
+   010/030 - [TMPDIR/xml_help] xmlAsText.....passed
+   011/030 - [TMPDIR/xml_help] xmlDTD........passed
+   012/030 - [TMPDIR/xml_help] xmlDelete.....passed
+   013/030 - [TMPDIR/xml_help] xmlDocument...passed
+   014/030 - [TMPDIR/xml_help] xmlDump.......passed
+   015/030 - [TMPDIR/xml_help] xmlElement....passed
+   016/030 - [TMPDIR/xml_help] xmlFormat.....passed
+   017/030 - [TMPDIR/xml_help] xmlGetNsByHref passed
+   018/030 - [TMPDIR/xml_help] xmlGetNsByPrefix passed
+   019/030 - [TMPDIR/xml_help] xmlGetOpenDocs passed
+   020/030 - [TMPDIR/xml_help] xmlIsValidObject passed
+   021/030 - [TMPDIR/xml_help] xmlNs.........passed
+   022/030 - [TMPDIR/xml_help] xmlRead.......passed
+   023/030 - [TMPDIR/xml_help] xmlReadStr....passed
+   024/030 - [TMPDIR/xml_help] xmlRelaxNG....passed
+   025/030 - [TMPDIR/xml_help] xmlRemove.....passed
+   026/030 - [TMPDIR/xml_help] xmlSchema.....passed
+   027/030 - [TMPDIR/xml_help] xmlSetAttributes passed
+   028/030 - [TMPDIR/xml_help] xmlValidate...passed
+   029/030 - [TMPDIR/xml_help] xmlWrite......passed
+   030/030 - [TMPDIR/xml_help] xmlXPath......passed
+
+
+   --------------------------------------------------------------------------
+   Summary
+
+   tests             30 - 100 % 
+   passed            30 - 100 % 
+   failed             0 -   0 % 
+   skipped            0 -   0 % 
+   length             38.82 sec 
+   --------------------------------------------------------------------------
+example_run("core", "argn");
+   TMPDIR = TMPDIR
+
+   001/001 - [TMPDIR/core_help] : 
+
+   001/001 - [TMPDIR/core_help] argn.........passed
+
+
+   --------------------------------------------------------------------------
+   Summary
+
+   tests              1 - 100 % 
+   passed             1 - 100 % 
+   failed             0 -   0 % 
+   skipped            0 -   0 % 
+   length             1.19 sec 
+   --------------------------------------------------------------------------
+example_run("core", ["argn"; "insertion"]);
+   TMPDIR = TMPDIR
+
+   001/001 - [TMPDIR/core_help] : 
+
+   001/002 - [TMPDIR/core_help] argn.........passed
+   002/002 - [TMPDIR/core_help] insertion....passed
+
+
+   --------------------------------------------------------------------------
+   Summary
+
+   tests              2 - 100 % 
+   passed             2 - 100 % 
+   failed             0 -   0 % 
+   skipped            0 -   0 % 
+   length             2.38 sec 
+   --------------------------------------------------------------------------
+example_run("core", "argn", "en_US");
+   TMPDIR = TMPDIR
+
+   001/001 - [TMPDIR/core_help] : 
+
+   001/001 - [TMPDIR/core_help] argn.........passed
+
+
+   --------------------------------------------------------------------------
+   Summary
+
+   tests              1 - 100 % 
+   passed             1 - 100 % 
+   failed             0 -   0 % 
+   skipped            0 -   0 % 
+   length             1.18 sec 
+   --------------------------------------------------------------------------
+example_run("core", "argn", "en_US", "no_check_error_output");
+   TMPDIR = TMPDIR
+
+   001/001 - [TMPDIR/core_help] : 
+
+   001/001 - [TMPDIR/core_help] argn.........passed
+
+
+   --------------------------------------------------------------------------
+   Summary
+
+   tests              1 - 100 % 
+   passed             1 - 100 % 
+   failed             0 -   0 % 
+   skipped            0 -   0 % 
+   length             1.15 sec 
+   --------------------------------------------------------------------------
+example_run("core", "argn", "en_US", "no_check_error_output", TMPDIR + "/example_run.xml");
+   TMPDIR = TMPDIR
+
+   001/001 - [TMPDIR/core_help] : 
+
+   001/001 - [TMPDIR/core_help] argn.........passed
+
+
+   --------------------------------------------------------------------------
+   Summary
+
+   tests              1 - 100 % 
+   passed             1 - 100 % 
+   failed             0 -   0 % 
+   skipped            0 -   0 % 
+   length             1.19 sec 
+   --------------------------------------------------------------------------
+   Export to          TMPDIR/example_run.xml 
+   --------------------------------------------------------------------------
diff --git a/scilab/modules/development_tools/tests/unit_tests/example_run.tst b/scilab/modules/development_tools/tests/unit_tests/example_run.tst
new file mode 100644 (file)
index 0000000..2f4f1eb
--- /dev/null
@@ -0,0 +1,40 @@
+// =============================================================================
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+// Copyright (C) 2012 - Scilab Enterprises - Vincent COUVERT
+//
+//  This file is distributed under the same license as the Scilab package.
+// =============================================================================
+
+// <-- CLI SHELL MODE -->
+
+// Test errors
+refMsg = msprintf(gettext("%s: Wrong type for input argument #%d: A row array of strings expected.\n"), "example_run", 1);
+assert_checkerror("example_run(10);", refMsg);
+refMsg = msprintf(gettext("%s: Wrong size for input argument #%d: A row array of strings expected.\n"), "example_run", 1);
+assert_checkerror("example_run([""core"",""xml""]);", refMsg);
+
+refMsg = msprintf(gettext("%s: Wrong type for input argument #%d: A row array of strings or empty matrix expected.\n"), "example_run", 2);
+assert_checkerror("example_run(""core"", 12);", refMsg);
+refMsg = msprintf(gettext("%s: Wrong size for input argument #%d: A row array of strings or empty matrix expected.\n"), "example_run", 2);
+assert_checkerror("example_run(""core"", [""argn"", ""insertion""]);", refMsg);
+
+refMsg = msprintf(gettext("%s: Wrong type for input argument #%d: A string expected.\n"), "example_run", 3);
+assert_checkerror("example_run(""core"", ""argn"", 12);", refMsg);
+refMsg = msprintf(gettext("%s: Wrong size for input argument #%d: A string expected.\n"), "example_run", 3);
+assert_checkerror("example_run(""core"", ""argn"", [""en_US"", ""fr_FR""]);", refMsg);
+
+refMsg = msprintf(gettext("%s: Wrong value for input argument #%d: A Scilab module name expected.\n"), "example_run", 1);
+assert_checkerror("example_run(""toto"");", refMsg);
+
+refMsg = msprintf(gettext("%s: Wrong value for input argument #%d: A ''%s'' module function name expected.\n"), "example_run", 2, "core");
+assert_checkerror("example_run(""core"", ""doesnotexistsname"");", refMsg);
+
+refMsg = msprintf(gettext("%s: Wrong value for input argument #%d: A valid language expected.\n"), "example_run", 3);
+assert_checkerror("example_run(""core"", ""argn"", ""aa_BB"");", refMsg);
+
+example_run("xml");
+example_run("core", "argn");
+example_run("core", ["argn"; "insertion"]);
+example_run("core", "argn", "en_US");
+example_run("core", "argn", "en_US", "no_check_error_output");
+example_run("core", "argn", "en_US", "no_check_error_output", TMPDIR + "/example_run.xml");