org-tests/index.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) NEW(n)
   5 #+TITLE:      Testing Org
   6 #+AUTHOR:     Worg people
   7 #+EMAIL:      bzg AT altern DOT org
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 # This file is the default header for new Org files in Worg.  Feel free
  13 # to tailor it to your needs.
  14
  15 [[file:../index.org][{Back to Worg's index}]]
  16
  17
  18 * Why test?
  19
  20 Org-mode has grown into a popular large and feature-rich application,
  21 on which development often happens at a great pace. Indeed, feature
  22 requests posted on the [[file:org-mailing-list.org][Org mailing list]] are frequently developed and
  23 published within hours of the request.
  24
  25 The down-side of such rapid development is that on some occasions, one
  26 of the many patches, features, or [[http://en.wikipedia.org/wiki/Code_refactoring][refactorings]] being applied to the
  27 code-base may unintentionally cause unexpected behavior within
  28 Org-mode. This is known as a [[http://en.wikipedia.org/wiki/Software_regression][software regression]]. The larger and more
  29 complex Org-mode becomes, the more you may expect to see such software
  30 regressions.
  31
  32 One concern with introducing software regressions is that the
  33 regression may not be immediately obvious to users. Indeed it can be
  34 hours, days, or even months before an Org-mode user moves to export an
  35 important schedule, when "bang" - the regression has reared its ugly
  36 head.
  37
  38 The solution to avoiding software regressions? [[http://en.wikipedia.org/wiki/Regression_testing][Regression Testing!]]
  39 With a regression test suite the developer can run the tests prior to
  40 committing their change, to ensure their additions do not break the
  41 regression tests.
  42
  43 Of course a regression test suite is only as good as the number of
  44 regression tests within it, and this is where Org-mode users can help.
  45
  46 * Running the current test suite
  47
  48 So long as you are on an up-to-date release of Org-mode you may run
  49 the tests on your local setup. To update Org-mode check out the
  50 [[http://orgmode.org/worg/org-faq.html][org FAQ page]]. Note, the test suite will run on versions of Emacs back
  51 to version 22.
  52
  53 A pre-requisite for running the tests is the [[http://www.emacswiki.org/emacs/ErtTestLibrary][ERT test library]]. This
  54 may be obtained easily as follows.
  55
  56 ** Emacs-22 / Emacs-23
  57
  58 In Emacs-22 and Emacs-23 you will need to download the test files
  59 _ert.el_ and _ert-x.el_ to your testing directory. This may be
  60 accomplished with the following commands entered on the command line.
  61
  62 : cd /path/to/org-mode/testing
  63 : curl -O https://github.com/mirrors/emacs/raw/master/lisp/emacs-lisp/ert.el
  64 : curl -O https://github.com/mirrors/emacs/raw/master/lisp/emacs-lisp/ert-x.el
  65
  66 Alternatively you may download the files within your browser.
  67
  68  - browse to [[https://github.com/mirrors/emacs/tree/master/lisp/emacs-lisp][github.com/mirrors/emacs/lisp/emacs-lisp]]
  69  - right click ert.el link and select _download linked file_ (or
  70    equivalent) and save to org-mode/testing/ert.el
  71  - right click ert-x.el link and select _download linked file_ (or
  72    equivalent) and save to org-mode/testing/ert-x.el
  73
  74 Thats it - you may now run the tests.
  75
  76 ** Emacs-24
  77
  78 Emacs-24 includes ERT, so nothing to do.
  79
  80 ** Run tests from the command line
  81
  82 To run the tests from the command line (without loading your personal
  83 configurations) use the following commands (Note, if you have more
  84 than one version of Emacs on your system, you may need to include the
  85 full path to the required Emacs executable).
  86
  87 : cd /path/to/org-mode/testing
  88 : Emacs -Q -batch -l org-test.el -eval "(setq org-confirm-babel-evaluate nil)" -f org-test-run-batch-tests'
  89
  90 ** Run tests from within Emacs
  91
  92 To run the tests from within Emacs itself.
  93
  94 : M-x load-file RET /path/to/org-mode/testing/org-test.el
  95 : M-x org-test-run-all-tests
  96
  97 * Can I write tests?
  98
  99 Most certainly! Even if you're not a lisp programmer, you may still
 100 help prevent regressions and greatly improve the stability of
 101 Org-mode. In fact, thanks to the growing number of test-macros that
 102 are available you can write regression tests with very minimal lisp
 103 knowledge, and you are also likely to greatly improve your knowledge
 104 of lisp as a result. And the more tests you write, the more confident
 105 you may be that your personal use of the many Org-mode features
 106 available has not been affected by regression.
 107
 108 And of course, any help toward improving the Org-mode test-suite is
 109 highly appreciated.
 110
 111 * Preparing to write tests
 112
 113 Coming soon...
 114
 115 * Tutorial
 116
 117 Coming soon...
 118
 119 * Testing Utilities
 120
 121 Several useful utilities exist to make the practice of writing tests
 122 even easier. These are available from the Org-mode repository as a
 123 seperate git sub-module. Assuming you have cloned Org-mode using git,
 124 you may install these extra utilities with the following git commands.
 125
 126 : cd /path/to/org-mode
 127 : git submodule init
 128 : git submodule update
 129
 130 * Aims
 131
 132 - Help all non-programmers to help:
 133   - Link to tutorials on debugging, emacs debugger...
 134
 135 - Create simple packages with test data, and place them here for download:
 136   - Directory trees with org-files for export-stress-testing.
 137   - One Org-file per bug to prevent regression.
 138   - Name and add corner cases.
 139
 140 - Create automated tests to programm against.
 141
 142 * Ideas for test
 143
 144 - Verify the output of tests with tools like =diff= (think /export/ here).
 145 - http://www.emacswiki.org/emacs-fr/UnitTesting
 146
 147 * What we need to know to actually write tests
 148
 149 The tutorial I'd need to write a test is one which lays out code I
 150 could copy and paste to do the following
 151
 152 ** setup the test environment
 153
 154    - create a test directory
 155    - create a sample test.org file
 156    - put the cursor in a particular place
 157
 158 ** run the command we need to test
 159
 160   - hit the 'TAB' key, or C-c C-c (some folks might need to be reminded how to
 161     find out exactly what command is actually being run  when you hit a
 162     keystroke. And some of me might need to be told what  lisp-code to use when
 163     the keystroke runs different commands at  different places in a file)
 164   - reformat a table
 165   - clock in/out
 166   - create the agenda
 167   - export .html .ics .dvi file
 168
 169 ** How do we specify the correct result???
 170
 171   - check that the headline folded properly.  What's the lisp code for getting
 172     the folded string as displayed?
 173   - check that the cursor is where it should be? especially when the cursor is
 174     near elipses...
 175   - check that the agenda is built properly.  What's the lisp code for getting
 176     the agenda as a string?
 177   - check that the exported files are correct.  Maybe the right suggestion is to
 178     run the export on two different files, so the test  can focus on the 'diff'
 179     between them.  That way different people who  run the same test on different
 180     hosts can get the same result.
 181
 182
 183 *** ERT Example
 184
 185 I implemented a toy test of org's html export facility using ert.el.
 186 See [[file:ert-publish-test.el]] for the implementation.  To run the test
 187 open up org-publish-test.el, and =M-x eval-buffer=.  This should load
 188 ert, and run the simple html export test.
 189
 190 * COMMENT buffer dictionary
 191
 192  LocalWords:  ert el EmacsLispExpectations org's