* Bug 16274 fixed: assert_checkequal() with Nan or void in containers
[scilab.git] / 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>