Mercurial > hg > xemacs-beta

comparison man/internals/internals.texi @ 1135:9eddcb9548e2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2002-12-02 17:56:58 by stephent] texinfo improvements <87d6okxq4i.fsf@tleepslib.sk.tsukuba.ac.jp>
author stephent
date Mon, 02 Dec 2002 17:57:09 +0000
parents 2c2ff019dd33
children c1553814932e
comparison
equal deleted inserted replaced
1134:dd61dd14b2a4 1135:9eddcb9548e2
3468 3468
3469 @example 3469 @example
3470 $ xemacs -batch -l test-harness.elc -f batch-test-emacs TEST-FILE 3470 $ xemacs -batch -l test-harness.elc -f batch-test-emacs TEST-FILE
3471 @end example 3471 @end example
3472 3472
3473 If something goes wrong, you can run the test suite interactively by 3473 If a test fails and you need more information, you can run the test
3474 loading @file{test-harness.el} into a running XEmacs and typing 3474 suite interactively by loading @file{test-harness.el} into a running
3475 @kbd{M-x test-emacs-test-file RET <filename> RET}. You will see a log of 3475 XEmacs and typing @kbd{M-x test-emacs-test-file RET <filename> RET}.
3476 passed and failed tests, which should allow you to investigate the 3476 You will see a log of passed and failed tests, which should allow you to
3477 source of the error and ultimately fix the bug. 3477 investigate the source of the error and ultimately fix the bug. If you
3478 are not capable of, or don't have time for, debugging it yourself,
3479 please do report the failures using @kbd{M-x report-emacs-bug} or
3480 @kbd{M-x build-report}.
3481
3482 @deffn Command test-emacs-test-file file
3483 Runs the tests in @var{file}. @file{test-harness.el} must be loaded.
3484 Defines all the macros described in this node, and undefines them when
3485 done.
3486 @end deffn
3478 3487
3479 Adding a new test file is trivial: just create a new file here and it 3488 Adding a new test file is trivial: just create a new file here and it
3480 will be run. There is no need to byte-compile any of the files in 3489 will be run. There is no need to byte-compile any of the files in
3481 this directory---the test-harness will take care of any necessary 3490 this directory---the test-harness will take care of any necessary
3482 byte-compilation. 3491 byte-compilation.
3483 3492
3484 Look at the existing test cases for the examples of coding test cases. 3493 Look at the existing test cases for the examples of coding test cases.
3485 It all boils down to your imagination and judicious use of the macros 3494 It all boils down to your imagination and judicious use of the macros
3486 @code{Assert}, @code{Check-Error}, @code{Check-Error-Message}, and 3495 @code{Assert}, @code{Check-Error}, @code{Check-Error-Message}, and
3487 @code{Check-Message}. 3496 @code{Check-Message}. Note that all of these macros are defined only
3497 for the duration of the test: they do not exist in the global
3498 environment.
3499
3500 @deffn Macro Assert expr
3501 Check that @var{expr} is non-nil at this point in the test.
3502 @end deffn
3503
3504 @deffn Macro Check-Error expected-error body
3505 Check that execution of @var{body} causes @var{expected-error} to be
3506 signaled. @var{body} is a @code{progn}-like body, and may contain
3507 several expressions. @var{expected-error} is a symbol defined as
3508 an error by @code{define-error}.
3509 @end deffn
3510
3511 @deffn Macro Check-Error-Message expected-error expected-error-regexp body
3512 Check that execution of @var{body} causes @var{expected-error} to be
3513 signaled, and generate a message matching @var{expected-error-regexp}.
3514 @var{body} is a @code{progn}-like body, and may contain several
3515 expressions. @var{expected-error} is a symbol defined as an error
3516 by @code{define-error}.
3517 @end deffn
3518
3519 @deffn Macro Check-Message expected-message body
3520 Check that execution of @var{body} causes @var{expected-message} to be
3521 generated (using @code{message} or a similar function). @var{body} is a
3522 @code{progn}-like body, and may contain several expressions.
3523 @end deffn
3488 3524
3489 Here's a simple example checking case-sensitive and case-insensitive 3525 Here's a simple example checking case-sensitive and case-insensitive
3490 comparisons from @file{case-tests.el}. 3526 comparisons from @file{case-tests.el}.
3491 3527
3492 @example 3528 @example
3507 (Assert (not (search-forward "Test buffer" nil t))) 3543 (Assert (not (search-forward "Test buffer" nil t)))
3508 (goto-char (point-min)) 3544 (goto-char (point-min))
3509 (Assert (eq (search-forward "Test Buffer" nil t) 12)))) 3545 (Assert (eq (search-forward "Test Buffer" nil t) 12))))
3510 @end example 3546 @end example
3511 3547
3512 This example could be inserted in a file in @file{tests/automated}, and 3548 This example could be saved in a file in @file{tests/automated}, and it
3513 it would be a complete test, automatically executed when you run 3549 would constitute a complete test, automatically executed when you run
3514 @kbd{make check} after building XEmacs. More complex tests may require 3550 @kbd{make check} after building XEmacs. More complex tests may require
3515 substantial temporary scaffolding to create the environment that elicits 3551 substantial temporary scaffolding to create the environment that elicits
3516 the bugs, but the top-level Makefile and @file{test-harness.el} handle 3552 the bugs, but the top-level @file{Makefile} and @file{test-harness.el}
3517 the running and collection of results from the @code{Assert}, 3553 handle the running and collection of results from the @code{Assert},
3518 @code{Check-Error}, @code{Check-Error-Message}, and @code{Check-Message} 3554 @code{Check-Error}, @code{Check-Error-Message}, and @code{Check-Message}
3519 macros. 3555 macros.
3556
3557 Don't suppress tests just because they're due to known bugs not yet
3558 fixed---use the @code{Known-Bug-Expect-Failure} wrapper macro to mark
3559 them.
3560
3561 @deffn Macro Known-Bug-Expect-Failure body
3562 Arrange for failing tests in @var{body} to generate messages prefixed
3563 with "KNOWN BUG:" instead of "FAIL:". @var{body} is a @code{progn}-like
3564 body, and may contain several tests.
3565 @end deffn
3566
3567 A lot of the tests we run push limits; suppress Ebola warning messages
3568 with the @code{Ignore-Ebola} wrapper macro.
3569
3570 @deffn Macro Ignore-Ebola body
3571 Suppress Ebola warning messages while running tests in @var{body}.
3572 @var{body} is a @code{progn}-like body, and may contain several tests.
3573 @end deffn
3574
3575 Both macros are defined temporarily within the test function. Simple
3576 examples:
3577
3578 @example
3579 ;; Apparently Ignore-Ebola is a solution with no problem to address.
3580 ;; There are no examples in 21.5, anyway.
3581
3582 ;; from regexp-tests.el
3583 (Known-Bug-Expect-Failure
3584 (Assert (not (string-match "\\b" "")))
3585 (Assert (not (string-match " \\b" " "))))
3586 @end example
3520 3587
3521 In general, you should avoid using functionality from packages in your 3588 In general, you should avoid using functionality from packages in your
3522 tests, because you can't be sure that everyone will have the required 3589 tests, because you can't be sure that everyone will have the required
3523 package. However, if you've got a test that works, by all means add it. 3590 package. However, if you've got a test that works, by all means add it.
3524 Simply wrap the test in an appropriate test, add a notice that the test 3591 Simply wrap the test in an appropriate test, add a notice that the test
3525 was skipped, and update the @code{skipped-test-reasons} hashtable. 3592 was skipped, and update the @code{skipped-test-reasons} hashtable. The
3526 Here's an example from @file{syntax-tests.el}: 3593 wrapper macro @code{Skip-Test-Unless} is provided to handle common
3594 cases.
3595
3596 @defvar skipped-test-reasons
3597 Hash table counting the number of times a particular reason is given for
3598 skipping tests. This is only defined within @code{test-emacs-test-file}.
3599 @end defvar
3600
3601 @deffn Macro Skip-Test-Unless prerequisite reason description body
3602 @var{prerequisite} is usually a feature test (@code{featurep},
3603 @code{boundp}, @code{fboundp}). @var{reason} is a string describing the
3604 prerequisite; it must be unique because it is used as a hash key in a
3605 table of reasons for skipping tests. @var{description} describes the
3606 tests being skipped, for the test result summary. @var{body} is a
3607 @code{progn}-like body, and may contain several tests.
3608 @end deffn
3609
3610 @code{Skip-Test-Unless} is defined temporarily within the test function.
3611 Here's an example of usage from @file{syntax-tests.el}:
3527 3612
3528 @example 3613 @example
3529 ;; Test forward-comment at buffer boundaries 3614 ;; Test forward-comment at buffer boundaries
3530 (with-temp-buffer 3615 (with-temp-buffer
3531
3532 ;; try to use exactly what you need: featurep, boundp, fboundp 3616 ;; try to use exactly what you need: featurep, boundp, fboundp
3533 (if (not (fboundp 'c-mode)) 3617 (Skip-Test-Unless (fboundp 'c-mode)
3534 3618 "c-mode unavailable"
3535 ;; We should provide a standard function for this boilerplate, 3619 "comment and parse-partial-sexp tests"
3536 ;; probably called `Skip-Test' -- check for that API with C-h f
3537 (let* ((reason "c-mode unavailable")
3538 (count (gethash reason skipped-test-reasons)))
3539 (puthash reason (if (null count) 1 (1+ count))
3540 skipped-test-reasons)
3541 (Print-Skip "comment and parse-partial-sexp tests" reason))
3542
3543 ;; and here's the test code 3620 ;; and here's the test code
3544 (c-mode) 3621 (c-mode)
3545 (insert "// comment\n") 3622 (insert "// comment\n")
3546 (forward-comment -2) 3623 (forward-comment -2)
3547 (Assert (eq (point) (point-min))) 3624 (Assert (eq (point) (point-min)))
3551 (forward-comment 2) 3628 (forward-comment 2)
3552 (Assert (eq (point) (point-max))) 3629 (Assert (eq (point) (point-max)))
3553 (parse-partial-sexp point (point-max))))) 3630 (parse-partial-sexp point (point-max)))))
3554 @end example 3631 @end example
3555 3632
3556 @code{Skip-Test} is intended for use with features that are normally 3633 @code{Skip-Test-Unless} is intended for use with features that are normally
3557 present in typical configurations. For truly optional features, or 3634 present in typical configurations. For truly optional features, or
3558 tests that apply to one of several alternative implementations (eg, to 3635 tests that apply to one of several alternative implementations (eg, to
3559 GTK widgets, but not Athena, Motif, MS Windows, or Carbon), simply 3636 GTK widgets, but not Athena, Motif, MS Windows, or Carbon), simply
3560 silently omit the test. 3637 silently suppress the test if the feature is not available.
3561 3638
3562 3639
3563 @node CVS Techniques, A Summary of the Various XEmacs Modules, Regression Testing XEmacs, Top 3640 @node CVS Techniques, A Summary of the Various XEmacs Modules, Regression Testing XEmacs, Top
3564 @chapter CVS Techniques 3641 @chapter CVS Techniques
3565 @cindex CVS techniques 3642 @cindex CVS techniques