I386LINUX/util/I386LINUX/doc/postgresql/html/regress-evaluation.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >Test Evaluation</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="Regression Tests"
  16 HREF="regress.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="Regression Tests"
  19 HREF="regress.html"><LINK
  20 REL="NEXT"
  21 TITLE="Platform-specific comparison files"
  22 HREF="regress-platform.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="SECT1"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="regress.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="regress.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 >Chapter 26. Regression Tests</TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="regress.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="regress-platform.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><DIV
  91 CLASS="SECT1"
  92 ><H1
  93 CLASS="SECT1"
  94 ><A
  95 NAME="REGRESS-EVALUATION"
  96 >26.2. Test Evaluation</A
  97 ></H1
  98 ><P
  99 >    Some properly installed and fully functional
 100     <SPAN
 101 CLASS="PRODUCTNAME"
 102 >PostgreSQL</SPAN
 103 > installations can
 104     <SPAN
 105 CLASS="QUOTE"
 106 >"fail"</SPAN
 107 > some of these regression tests due to
 108     platform-specific artifacts such as varying floating-point representation
 109     and time zone support. The tests are currently evaluated using a simple
 110     <TT
 111 CLASS="COMMAND"
 112 >diff</TT
 113 > comparison against the outputs
 114     generated on a reference system, so the results are sensitive to
 115     small system differences.  When a test is reported as
 116     <SPAN
 117 CLASS="QUOTE"
 118 >"failed"</SPAN
 119 >, always examine the differences between
 120     expected and actual results; you may well find that the
 121     differences are not significant.  Nonetheless, we still strive to
 122     maintain accurate reference files across all supported platforms,
 123     so it can be expected that all tests pass.
 124    </P
 125 ><P
 126 >    The actual outputs of the regression tests are in files in the
 127     <TT
 128 CLASS="FILENAME"
 129 >src/test/regress/results</TT
 130 > directory. The test
 131     script uses <TT
 132 CLASS="COMMAND"
 133 >diff</TT
 134 > to compare each output
 135     file against the reference outputs stored in the
 136     <TT
 137 CLASS="FILENAME"
 138 >src/test/regress/expected</TT
 139 > directory.  Any
 140     differences are saved for your inspection in
 141     <TT
 142 CLASS="FILENAME"
 143 >src/test/regress/regression.diffs</TT
 144 >.  (Or you
 145     can run <TT
 146 CLASS="COMMAND"
 147 >diff</TT
 148 > yourself, if you prefer.)
 149    </P
 150 ><DIV
 151 CLASS="SECT2"
 152 ><H2
 153 CLASS="SECT2"
 154 ><A
 155 NAME="AEN19742"
 156 >26.2.1. Error message differences</A
 157 ></H2
 158 ><P
 159 >     Some of the regression tests involve intentional invalid input
 160      values.  Error messages can come from either the
 161      <SPAN
 162 CLASS="PRODUCTNAME"
 163 >PostgreSQL</SPAN
 164 > code or from the host
 165      platform system routines. In the latter case, the messages may
 166      vary between platforms, but should reflect similar
 167      information. These differences in messages will result in a
 168      <SPAN
 169 CLASS="QUOTE"
 170 >"failed"</SPAN
 171 > regression test that can be validated by
 172      inspection.
 173     </P
 174 ></DIV
 175 ><DIV
 176 CLASS="SECT2"
 177 ><H2
 178 CLASS="SECT2"
 179 ><A
 180 NAME="AEN19747"
 181 >26.2.2. Locale differences</A
 182 ></H2
 183 ><P
 184 >     If you run the tests against an already-installed server that was
 185      initialized with a collation-order locale other than C, then
 186      there may be differences due to sort order and follow-up
 187      failures.  The regression test suite is set up to handle this
 188      problem by providing alternative result files that together are
 189      known to handle a large number of locales.  For example, for the
 190      <TT
 191 CLASS="LITERAL"
 192 >char</TT
 193 > test, the expected file
 194      <TT
 195 CLASS="FILENAME"
 196 >char.out</TT
 197 > handles the <TT
 198 CLASS="LITERAL"
 199 >C</TT
 200 > and <TT
 201 CLASS="LITERAL"
 202 >POSIX</TT
 203 > locales,
 204      and the file <TT
 205 CLASS="FILENAME"
 206 >char_1.out</TT
 207 > handles many other
 208      locales.  The regression test driver will automatically pick the
 209      best file to match against when checking for success and for
 210      computing failure differences.  (This means that the regression
 211      tests cannot detect whether the results are appropriate for the
 212      configured locale.  The tests will simply pick the one result
 213      file that works best.)
 214     </P
 215 ><P
 216 >     If for some reason the existing expected files do not cover some
 217      locale, you can add a new file.  The naming scheme is
 218      <TT
 219 CLASS="LITERAL"
 220 ><VAR
 221 CLASS="REPLACEABLE"
 222 >testname</VAR
 223 >_<VAR
 224 CLASS="REPLACEABLE"
 225 >digit</VAR
 226 >.out</TT
 227 >.
 228      The actual digit is not significant.  Remember that the
 229      regression test driver will consider all such files to be equally
 230      valid test results.  If the test results are platform-specific,
 231      the technique described in <A
 232 HREF="regress-platform.html"
 233 >Section 26.3</A
 234 >
 235      should be used instead.
 236     </P
 237 ></DIV
 238 ><DIV
 239 CLASS="SECT2"
 240 ><H2
 241 CLASS="SECT2"
 242 ><A
 243 NAME="AEN19760"
 244 >26.2.3. Date and time differences</A
 245 ></H2
 246 ><P
 247 >     A few of the queries in the <TT
 248 CLASS="FILENAME"
 249 >horology</TT
 250 > test will
 251      fail if you run the test on the day of a daylight-saving time
 252      changeover, or the day after one.  These queries expect that
 253      the intervals between midnight yesterday, midnight today and
 254      midnight tomorrow are exactly twenty-four hours --- which is wrong
 255      if daylight-saving time went into or out of effect meanwhile.
 256     </P
 257 ><DIV
 258 CLASS="NOTE"
 259 ><BLOCKQUOTE
 260 CLASS="NOTE"
 261 ><P
 262 ><B
 263 >Note: </B
 264 >      Because USA daylight-saving time rules are used, this problem always
 265       occurs on the first Sunday of April, the last Sunday of October,
 266       and their following Mondays, regardless of when daylight-saving time
 267       is in effect where you live.  Also note that the problem appears or
 268       disappears at midnight Pacific time (UTC-7 or UTC-8), not midnight
 269       your local time.  Thus the failure may appear late on Saturday or
 270       persist through much of Tuesday, depending on where you live.
 271      </P
 272 ></BLOCKQUOTE
 273 ></DIV
 274 ><P
 275 >     Most of the date and time results are dependent on the time zone
 276      environment.  The reference files are generated for time zone
 277      <TT
 278 CLASS="LITERAL"
 279 >PST8PDT</TT
 280 > (Berkeley, California), and there will be apparent
 281      failures if the tests are not run with that time zone setting.
 282      The regression test driver sets environment variable
 283      <TT
 284 CLASS="ENVAR"
 285 >PGTZ</TT
 286 > to <TT
 287 CLASS="LITERAL"
 288 >PST8PDT</TT
 289 >, which normally
 290      ensures proper results.  However, your operating system must provide
 291      support for the <TT
 292 CLASS="LITERAL"
 293 >PST8PDT</TT
 294 > time zone, or the time zone-dependent
 295      tests will fail. To verify that your machine does have this
 296      support, type the following:
 297 </P><PRE
 298 CLASS="SCREEN"
 299 >env TZ=PST8PDT date</PRE
 300 ><P>
 301      The command above should have returned the current system time in
 302      the <TT
 303 CLASS="LITERAL"
 304 >PST8PDT</TT
 305 > time zone. If the <TT
 306 CLASS="LITERAL"
 307 >PST8PDT</TT
 308 > time zone is not available,
 309      then your system may have returned the time in UTC. If the
 310      <TT
 311 CLASS="LITERAL"
 312 >PST8PDT</TT
 313 > time zone is missing, you can set the time zone
 314      rules explicitly:
 315 </P><PRE
 316 CLASS="PROGRAMLISTING"
 317 >PGTZ='PST8PDT7,M04.01.0,M10.05.03'; export PGTZ</PRE
 318 ><P>
 319     </P
 320 ><P
 321 >     There appear to be some systems that do not accept the
 322      recommended syntax for explicitly setting the local time zone
 323      rules; you may need to use a different <TT
 324 CLASS="ENVAR"
 325 >PGTZ</TT
 326 >
 327      setting on such machines.
 328     </P
 329 ><P
 330 >     Some systems using older time-zone libraries fail to apply
 331      daylight-saving corrections to dates before 1970, causing
 332      pre-1970 <ACRONYM
 333 CLASS="ACRONYM"
 334 >PDT</ACRONYM
 335 > times to be displayed in <ACRONYM
 336 CLASS="ACRONYM"
 337 >PST</ACRONYM
 338 > instead.  This will
 339      result in localized differences in the test results.
 340     </P
 341 ></DIV
 342 ><DIV
 343 CLASS="SECT2"
 344 ><H2
 345 CLASS="SECT2"
 346 ><A
 347 NAME="AEN19781"
 348 >26.2.4. Floating-point differences</A
 349 ></H2
 350 ><P
 351 >     Some of the tests involve computing 64-bit floating-point numbers (<TT
 352 CLASS="TYPE"
 353 >double
 354      precision</TT
 355 >) from table columns. Differences in
 356      results involving mathematical functions of <TT
 357 CLASS="TYPE"
 358 >double
 359      precision</TT
 360 > columns have been observed.  The <TT
 361 CLASS="LITERAL"
 362 >float8</TT
 363 > and
 364      <TT
 365 CLASS="LITERAL"
 366 >geometry</TT
 367 > tests are particularly prone to small differences
 368      across platforms, or even with different compiler optimization options.
 369      Human eyeball comparison is needed to determine the real
 370      significance of these differences which are usually 10 places to
 371      the right of the decimal point.
 372     </P
 373 ><P
 374 >     Some systems display minus zero as <TT
 375 CLASS="LITERAL"
 376 >-0</TT
 377 >, while others
 378      just show <TT
 379 CLASS="LITERAL"
 380 >0</TT
 381 >.
 382     </P
 383 ><P
 384 >     Some systems signal errors from <CODE
 385 CLASS="FUNCTION"
 386 >pow()</CODE
 387 > and
 388      <CODE
 389 CLASS="FUNCTION"
 390 >exp()</CODE
 391 > differently from the mechanism
 392      expected by the current <SPAN
 393 CLASS="PRODUCTNAME"
 394 >PostgreSQL</SPAN
 395 >
 396      code.
 397     </P
 398 ></DIV
 399 ><DIV
 400 CLASS="SECT2"
 401 ><H2
 402 CLASS="SECT2"
 403 ><A
 404 NAME="AEN19795"
 405 >26.2.5. Row ordering differences</A
 406 ></H2
 407 ><P
 408 >You might see differences in which the same rows are output in a
 409 different order than what appears in the expected file.  In most cases
 410 this is not, strictly speaking, a bug.  Most of the regression test
 411 scripts are not so pedantic as to use an <TT
 412 CLASS="LITERAL"
 413 >ORDER BY</TT
 414 > for every single
 415 <TT
 416 CLASS="LITERAL"
 417 >SELECT</TT
 418 >, and so their result row orderings are not well-defined
 419 according to the letter of the SQL specification.  In practice, since we are
 420 looking at the same queries being executed on the same data by the same
 421 software, we usually get the same result ordering on all platforms, and
 422 so the lack of <TT
 423 CLASS="LITERAL"
 424 >ORDER BY</TT
 425 > isn't a problem.  Some queries do exhibit
 426 cross-platform ordering differences, however.  (Ordering differences
 427 can also be triggered by non-C locale settings.)
 428     </P
 429 ><P
 430 >Therefore, if you see an ordering difference, it's not something to
 431 worry about, unless the query does have an <TT
 432 CLASS="LITERAL"
 433 >ORDER BY</TT
 434 > that your result
 435 is violating.  But please report it anyway, so that we can add an
 436 <TT
 437 CLASS="LITERAL"
 438 >ORDER BY</TT
 439 > to that particular query and thereby eliminate the bogus
 440 <SPAN
 441 CLASS="QUOTE"
 442 >"failure"</SPAN
 443 > in future releases.
 444     </P
 445 ><P
 446 >You might wonder why we don't order all the regression test queries explicitly to
 447 get rid of this issue once and for all.  The reason is that that would
 448 make the regression tests less useful, not more, since they'd tend
 449 to exercise query plan types that produce ordered results to the
 450 exclusion of those that don't.
 451     </P
 452 ></DIV
 453 ><DIV
 454 CLASS="SECT2"
 455 ><H2
 456 CLASS="SECT2"
 457 ><A
 458 NAME="AEN19806"
 459 >26.2.6. The <SPAN
 460 CLASS="QUOTE"
 461 >"random"</SPAN
 462 > test</A
 463 ></H2
 464 ><P
 465 >     There is at least one case in the <TT
 466 CLASS="LITERAL"
 467 >random</TT
 468 > test
 469      script that is intended to produce random results. This causes
 470      random to fail the regression test once in a while (perhaps once
 471      in every five to ten trials).  Typing
 472 </P><PRE
 473 CLASS="PROGRAMLISTING"
 474 >diff results/random.out expected/random.out</PRE
 475 ><P>
 476      should produce only one or a few lines of differences.  You need
 477      not worry unless the random test always fails in repeated
 478      attempts.  (On the other hand, if the random test is
 479      <SPAN
 480 CLASS="emphasis"
 481 ><I
 482 CLASS="EMPHASIS"
 483 >never</I
 484 ></SPAN
 485 > reported to fail even in many trials
 486      of the regression tests, you probably <SPAN
 487 CLASS="emphasis"
 488 ><I
 489 CLASS="EMPHASIS"
 490 >should</I
 491 ></SPAN
 492 >
 493      worry.)
 494     </P
 495 ></DIV
 496 ></DIV
 497 ><DIV
 498 CLASS="NAVFOOTER"
 499 ><HR
 500 ALIGN="LEFT"
 501 WIDTH="100%"><TABLE
 502 SUMMARY="Footer navigation table"
 503 WIDTH="100%"
 504 BORDER="0"
 505 CELLPADDING="0"
 506 CELLSPACING="0"
 507 ><TR
 508 ><TD
 509 WIDTH="33%"
 510 ALIGN="left"
 511 VALIGN="top"
 512 ><A
 513 HREF="regress.html"
 514 ACCESSKEY="P"
 515 >Prev</A
 516 ></TD
 517 ><TD
 518 WIDTH="34%"
 519 ALIGN="center"
 520 VALIGN="top"
 521 ><A
 522 HREF="index.html"
 523 ACCESSKEY="H"
 524 >Home</A
 525 ></TD
 526 ><TD
 527 WIDTH="33%"
 528 ALIGN="right"
 529 VALIGN="top"
 530 ><A
 531 HREF="regress-platform.html"
 532 ACCESSKEY="N"
 533 >Next</A
 534 ></TD
 535 ></TR
 536 ><TR
 537 ><TD
 538 WIDTH="33%"
 539 ALIGN="left"
 540 VALIGN="top"
 541 >Regression Tests</TD
 542 ><TD
 543 WIDTH="34%"
 544 ALIGN="center"
 545 VALIGN="top"
 546 ><A
 547 HREF="regress.html"
 548 ACCESSKEY="U"
 549 >Up</A
 550 ></TD
 551 ><TD
 552 WIDTH="33%"
 553 ALIGN="right"
 554 VALIGN="top"
 555 >Platform-specific comparison files</TD
 556 ></TR
 557 ></TABLE
 558 ></DIV
 559 ></BODY
 560 ></HTML
 561 >