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 Org-mode has grown a big and feature rich application. Help is always needed and
  19 highly appreciated. If you're not a lisp programmer, you still might help to
  20 prevent regressions and greatly improve the stability of Org-mode.
  21
  22 This page is meant to provide help with this kind of helping. We hope to provide
  23 all the information needed here, and hope to create tests for non-programmers
  24 too.
  25
  26 Currently we are in a very early planning phase, so will find only what we
  27 _want_ to do. If you're not a worger yet, you may as well post ideas or code to
  28 the great [[file:org-mailing-list.org][Org mailing list]].
  29
  30
  31 * Aims
  32
  33 - Help all non-programmers to help:
  34   - Link to tutorials on debugging, emacs debugger...
  35
  36 - Create simple packages with test data, and place them here for download:
  37   - Directory trees with org-files for export-stress-testing.
  38   - One Org-file per bug to prevent regression.
  39   - Name and add corner cases.
  40
  41 - Create automated tests to programm against.
  42
  43 * Ideas for test
  44
  45 - Veryfy the output of tests with tools like =diff= (think /export/ here).
  46 - http://www.emacswiki.org/emacs-fr/UnitTesting
  47
  48 * What we need to know to actually write tests
  49
  50 The tutorial I'd need to write a test is one which lays out code I
  51 could copy and paste to do the following
  52
  53 ** setup the test environment
  54
  55    - create a test directory
  56    - create a sample test.org file
  57    - put the cursor in a particular place
  58
  59 ** run the command we need to test
  60
  61   - hit the 'TAB' key, or C-c C-c (some folks might need to be reminded how to
  62     find out exactly what command is actually being run  when you hit a
  63     keystroke. And some of me might need to be told what  lisp-code to use when
  64     the keystroke runs different commands at  different places in a file)
  65   - reformat a table
  66   - clock in/out
  67   - create the agenda
  68   - export .html .ics .dvi file
  69
  70 ** How do we specify the correct result???
  71
  72   - check that the headline folded properly.  What's the lisp code for getting
  73     the folded string as displayed?
  74   - check that the cursor is where it should be? especially when the cursor is
  75     near elipses...
  76   - check that the agenda is built properly.  What's the lisp code for getting
  77     the agenda as a string?
  78   - check that the exported files are correct.  Maybe the right suggestion is to
  79     run the export on two different files, so the test  can focus on the 'diff'
  80     between them.  That way different people who  run the same test on different
  81     hosts can get the same result.
  82
  83 ** Testing tools
  84
  85 Many of the above questions (how to we setup and tear down tests, and
  86 how can we make and check assertions) will depend heavily on the
  87 chosen testing tool.  Two options posited to the list so far are...
  88
  89 - ERT :: (from http://github.com/ohler/ert/tree/master/ert.el) ert is
  90          a tool for automated testing, reporting results, as well as
  91          debugging errors
  92 - EmacsLispExpectations :: (from
  93      http://www.emacswiki.org/cgi-bin/emacs/EmacsLispExpectations) is
  94      a minimalist elisp testing framework based on
  95
  96 Both of these elisp files have been included in the =tools= directory
  97 inside this directory.
  98
  99 I've never used EmacsLispExpectations, so I can't make any reasonable
 100 judgment between the two, perhaps if someone can implement some tests
 101 in both we could come to some sort of agreement.
 102
 103 *** ERT Example
 104
 105 I implemented a toy test of org's html export facility using ert.el.
 106 See [[file:ert-publish-test.el]] for the implementation.  To run the test
 107 open up org-publish-test.el, and =M-x eval-buffer=.  This should load
 108 ert, and run the simple html export test.
 109
 110 * Clipboard
 111
 112 Running a minimal emacs should suppress custom config files:
 113 : emacs -q -l yourtest.el
 114
 115 Getting a list of all variables (incomplete):
 116 : grep -r defvar lisp/*.el
 117
 118 * COMMENT buffer dictionary
 119
 120  LocalWords:  ert el EmacsLispExpectations org's