org-tests/index.org

   1 #+TITLE:      Testing Org
   2 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   3 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   4 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   5 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) NEW(n)
   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 * Why test?
  18
  19 Org-mode has grown into a popular large and feature-rich application,
  20 on which development often happens at a great pace. Indeed, feature
  21 requests posted on the [[file:../org-mailing-list.org][Org mailing list]] are frequently developed and
  22 published within hours of the request.
  23
  24 The down-side of such rapid development is that on some occasions, one
  25 of the many patches, features, or [[https://en.wikipedia.org/wiki/Code_refactoring][refactorings]] being applied to the
  26 code-base may unintentionally cause unexpected behavior within
  27 Org-mode. This is known as a [[https://en.wikipedia.org/wiki/Software_regression][software regression]]. The larger and more
  28 complex Org-mode becomes, the more you may expect to see such software
  29 regressions.
  30
  31 One concern with introducing software regressions is that the
  32 regression may not be immediately obvious to users. Indeed it can be
  33 hours, days, or even months before an Org-mode user moves to export an
  34 important schedule, when "bang" - the regression has reared its ugly
  35 head.
  36
  37 The solution to avoiding software regressions? [[https://en.wikipedia.org/wiki/Regression_testing][Regression Testing!]]
  38 With a regression test suite the developer can run the tests prior to
  39 committing their change, to ensure their additions do not break the
  40 regression tests.
  41
  42 Naturally, a regression test suite is only as good as the number,
  43 quality, and coverage of regression tests within it, and this is where
  44 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 [[https://orgmode.org/worg/org-faq.html][org
  50 FAQ page]]. Note, the test suite will run on versions of Emacs back to
  51 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 That's 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 In recent versions of Emacs and Org-mode a test run can be triggered
  91 using the =make= program.
  92
  93 : cd /path/to/org-mode
  94 : make test
  95
  96 ** Run tests from within Emacs
  97
  98 To run the tests from within Emacs itself.
  99
 100 : M-x load-file RET /path/to/org-mode/testing/org-test.el
 101 : M-x org-test-run-all-tests
 102
 103 * Writing tests with minimal Emacs-lisp knowledge
 104
 105 Thanks to the growing number of test-macros that are being made
 106 available, it is becoming easier to write regression tests with
 107 minimal lisp knowledge, and you are also likely to greatly improve
 108 your knowledge of Emacs-lisp as a result. And the more tests you
 109 write, the more confident you may be that your personal use of the
 110 many Org-mode features available has not been affected by regression.
 111
 112 And of course, any help toward improving the Org-mode test-suite is
 113 highly appreciated.
 114
 115 * Preparing to write tests
 116
 117 Coming soon...
 118
 119 * Tutorial
 120
 121 Coming soon...
 122
 123 * Testing Utilities
 124
 125 Several useful utilities exist to make the practice of writing tests
 126 even easier. These are available from the Org-mode repository as a
 127 seperate git sub-module. Assuming you have cloned Org-mode using git,
 128 you may install these extra utilities with the following git commands.
 129
 130 : cd /path/to/org-mode
 131 : git submodule init
 132 : git submodule update
 133
 134 * Aims
 135
 136 - Help all non-programmers to help:
 137   - Link to tutorials on debugging, emacs debugger...
 138
 139 - Create simple packages with test data, and place them here for download:
 140   - Directory trees with org-files for export-stress-testing.
 141   - One Org-file per bug to prevent regression.
 142   - Name and add corner cases.
 143
 144 - Create automated tests to programm against.
 145
 146 * Ideas for test
 147
 148 - Verify the output of tests with tools like =diff= (think /export/ here).
 149 - http://www.emacswiki.org/emacs-fr/UnitTesting
 150
 151 * What we need to know to actually write tests
 152
 153 The tutorial I'd need to write a test is one which lays out code I
 154 could copy and paste to do the following:
 155
 156 ** setup the test environment
 157
 158    - create a test directory
 159    - create a sample test.org file
 160    - put the cursor in a particular place
 161
 162 ** run the command we need to test
 163
 164   - hit the =TAB= key, or =C-c C-c= (some folks might need to be reminded how to
 165     find out exactly what command is actually being run  when you hit a
 166     keystroke. And some of me might need to be told what  lisp-code to use when
 167     the keystroke runs different commands at  different places in a file)
 168   - reformat a table
 169   - clock in/out
 170   - create the agenda
 171   - export .html .ics .dvi files
 172
 173 ** How do we specify the correct result???
 174
 175   - check that the headline folded properly.  What's the lisp code for getting
 176     the folded string as displayed?
 177   - check that the cursor is where it should be? Especially when the cursor is
 178     near elipses...
 179   - check that the agenda is built properly.  What's the lisp code for getting
 180     the agenda as a string?
 181   - check that the exported files are correct.  Maybe the right suggestion is to
 182     run the export on two different files, so the test  can focus on the 'diff'
 183     between them.  That way different people who  run the same test on different
 184     hosts can get the same result.
 185
 186
 187 *** ERT Example
 188
 189 I implemented a toy test of org's html export facility using ert.el.
 190 See [[file:../code/elisp/ert-publish-test.el]] for the implementation.  To run the test
 191 open up org-publish-test.el, and =M-x eval-buffer=.  This should load
 192 ert, and run the simple html export test.
 193
 194 * COMMENT buffer dictionary
 195
 196  LocalWords:  ert el EmacsLispExpectations org's