scilab/modules/development_tools/help/en_US/assert/assert_checkequal.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  *
   4  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   5  * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin
   6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   7  * Copyright (C) 2019 - Samuel GOUGEON
   8  *
   9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  11  * This file was originally licensed under the terms of the CeCILL v2.1,
  12  * and continues to be available under such terms.
  13  * For more information, see the COPYING file which you should have received
  14  * along with this program.
  15  *
  16  -->
  17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
  19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
  20           xmlns:scilab="http://www.scilab.org" xml:id="assert_checkequal" xml:lang="en">
  21     <refnamediv>
  22         <refname>assert_checkequal</refname>
  23         <refpurpose>Check that computed and expected are equal.</refpurpose>
  24     </refnamediv>
  25     <refsynopsisdiv>
  26         <title>Syntax</title>
  27         <synopsis>
  28             assert_checkequal ( computed , expected )
  29             flag = assert_checkequal ( computed , expected )
  30             [flag,errmsg] = assert_checkequal ( computed , expected )
  31         </synopsis>
  32     </refsynopsisdiv>
  33     <refsection>
  34         <title>Parameters</title>
  35         <variablelist>
  36             <varlistentry>
  37                 <term>computed:</term>
  38                 <listitem>
  39                     <para> the computed result</para>
  40                 </listitem>
  41             </varlistentry>
  42             <varlistentry>
  43                 <term>expected :</term>
  44                 <listitem>
  45                     <para> the expected result</para>
  46                 </listitem>
  47             </varlistentry>
  48             <varlistentry>
  49                 <term>flag :</term>
  50                 <listitem>
  51                     <para> a boolean, %t if computed is equal to expected, %f if not</para>
  52                 </listitem>
  53             </varlistentry>
  54             <varlistentry>
  55                 <term>errmsg :</term>
  56                 <listitem>
  57                     <para>
  58                         a string, the error message. If flag==%t, then errormsg=="".
  59                         If flag==%f, then errmsg contains the error message.
  60                     </para>
  61                 </listitem>
  62             </varlistentry>
  63         </variablelist>
  64     </refsection>
  65     <refsection>
  66         <title>Description</title>
  67         <para>
  68             Performs silently if <varname>computed</varname> and <varname>expected</varname> are equal.
  69         </para>
  70         <para>
  71             For complex numbers: We compare first the real parts. In case of equality, we compare
  72             the imaginary parts.
  73         </para>
  74         <para>
  75             Matching Nan values are always considered equal.
  76         </para>
  77         <para>
  78             <literal>1/%z</literal> and <literal>2/(2*%z)</literal> are not equal: For the time
  79             being, Scilab does not normalize equivalent rationals.
  80         </para>
  81         <para>
  82             In containers, matching <literal>void</literal> elements are considered equal.
  83         </para>
  84         <para>
  85             If the comparison shows that computed is equal to expected,
  86             <itemizedlist>
  87                 <listitem>
  88                     <para>if the errmsg output variable is not used, an error is generated,</para>
  89                 </listitem>
  90                 <listitem>
  91                     <para>if the errmsg output variable is used, no error is generated.</para>
  92                 </listitem>
  93             </itemizedlist>
  94         </para>
  95     </refsection>
  96     <refsection>
  97         <title>Examples</title>
  98         <para>
  99             Tests with success:
 100         </para>
 101         <programlisting role="example"><![CDATA[
 102 assert_checkequal ( %T , %T );
 103 [flag , errmsg] = assert_checkequal ( [%T %F], [%T %F] );
 104 assert_checkequal ( %nan , %nan );
 105 c = complex(1, %nan)
 106 assert_checkequal (c, c);
 107 assert_checkequal ( sparse(%nan) , sparse(%nan) );
 108 assert_checkequal ( 2:$-1, 2:$-1 );
 109
 110 assert_checkequal ( ["abc" "" ascii([9 10 13])],  ["abc" "" ascii([9 10 13])] );
 111 assert_checkequal ( [gdf(), gda()], [gdf(), gda()]);
 112
 113 assert_checkequal ( list() , list() );
 114 assert_checkequal ( list(1,,3), list(1,,3) );
 115 assert_checkequal ( list(1,,list(,4)), list(1,,list(,4)) );
 116 assert_checkequal ( list(%nan,,7) , list(%nan,,7) );
 117
 118 sine = sin;
 119 assert_checkequal ( sin, sine );
 120 cosinus = cosd;
 121 assert_checkequal ( cosinus, cosd );
 122 assert_checkequal( iolib, iolib );
 123    ]]></programlisting>
 124         <para>
 125             Tests with failure:
 126         </para>
 127         <programlisting role="example"><![CDATA[
 128 assert_checkequal ( %F , %T );
 129 flag = assert_checkequal ( %F , %T );
 130 // No error produced :
 131 [flag , errmsg] = assert_checkequal ( %F , %T )
 132
 133 assert_checkequal ( [1 2], [3 4] )
 134 assert_checkequal ( 1 , [2 3] )
 135 assert_checkequal ( 1 , "b" )
 136 assert_checkequal ( "b", "B" )
 137 assert_checkequal ( 1+%s, 1+%z )
 138 assert_checkequal ( 1/%s, 2/(2*%s) )
 139
 140 assert_checkequal (list(2,,7), list(2,%F,8));
 141 assert_checkequal ( [gdf(), gda()], [gdf(), gdf()] );
 142 assert_checkequal ( sind, cosd );
 143 assert_checkequal ( iolib, corelib );
 144    ]]></programlisting>
 145    <screen><![CDATA[
 146 ...
 147 --> assert_checkequal (list(2,,7), list(2,%F,8));
 148 at line    22 of function assert_generror   ( SCI\modules\..\assert_generror.sci line 33 )
 149 at line   178 of function assert_checkequal ( SCI\modules\..\assert_checkequal.sci line 190 )
 150
 151 assert_checkequal: Assertion failed: expected(2)= F  while computed(2)= (void)
 152
 153 --> assert_checkequal ( [gdf(), gda()], [gdf(), gdf()] );
 154 at line    22 of function assert_generror   ( SCI\modules\..\assert_generror.sci line 33 )
 155 at line   178 of function assert_checkequal ( SCI\modules\..\assert_checkequal.sci line 190 )
 156
 157 assert_checkequal: Assertion failed: expected(2)= Figure(uid:55)  while computed(2)= Axes(uid:85)
 158
 159 --> assert_checkequal ( sind, cosd );
 160 at line    22 of function assert_generror   ( SCI\modules\..\assert_generror.sci line 33 )
 161 at line    82 of function assert_checkequal ( SCI\modules\..\assert_checkequal.sci line 94 )
 162
 163 assert_checkequal: Assertion failed: expected= cosd()  while computed= sind()
 164
 165 --> assert_checkequal ( iolib, corelib );
 166 at line    22 of function assert_generror   ( SCI\modules\..\assert_generror.sci line 33 )
 167 at line    95 of function assert_checkequal ( SCI\modules\..\assert_checkequal.sci line 107 )
 168
 169 assert_checkequal: Assertion failed: expected= lib@SCI\modules\core\macros\  while ..
 170                                      computed= lib@SCI\modules\io\macros\
 171 ]]></screen>
 172     </refsection>
 173     <refsection>
 174         <title>Bibliography</title>
 175         <para>"Automated Software Testing for Matlab", Steven Eddins, 2009</para>
 176     </refsection>
 177     <refsection>
 178         <title>History</title>
 179         <revhistory>
 180             <revision>
 181                 <revnumber>5.4.0</revnumber>
 182                 <revdescription>Function introduced
 183                 </revdescription>
 184             </revision>
 185             <revision>
 186                 <revnumber>6.1.0</revnumber>
 187                 <revdescription>
 188                     <itemizedlist>
 189                       <listitem>
 190                           The comparison of two implicit lists, Scilab functions, Scilab libraries,
 191                           built-in functions or graphic handles is now always possible and properly
 192                           done.
 193                       </listitem>
 194                       <listitem>
 195                           In two lists, void and Nan elements are now supported, and matching ones
 196                           are considered as equal.
 197                       </listitem>
 198                       <listitem>
 199                           Nan are now supported in input sparse matrices and are considered as equal.
 200                       </listitem>
 201                       <listitem>
 202                           When the test fails while inputs are arrays, the message now indicates
 203                           the index of the first mismatching element.
 204                       </listitem>
 205                   </itemizedlist>
 206                 </revdescription>
 207             </revision>
 208             <revision>
 209                 <revnumber>6.1.1</revnumber>
 210                 <revdescription>
 211                     Matching NaN or void elements in simple or nested containers are now considered equal.
 212                 </revdescription>
 213             </revision>
 214         </revhistory>
 215     </refsection>
 216 </refentry>