Automated testing
=================

Introduction
------------
The bash-completion package contains an automated test suite.  Running the tests should help verifying that bash-completion works as expected.  The tests are also very helpful in uncovering software regressions at an early stage.

The bash-completion test suite is written on top of the http://www.gnu.org/software/dejagnu/[DejaGnu] testing framework.  DejaGnu is written in http://expect.nist.gov[Expect], which in turn uses http://tcl.sourceforge.net[Tcl] -- Tool command language.




Installing DejaGnu
------------------

Installing DejaGnu should be easy using your local package manager.


Debian/Ubuntu
~~~~~~~~~~~~~

On Debian/Ubuntu you can use `apt-get`:
-------------
sudo apt-get install dejagnu
-------------
This should also install the necessary `expect` and `tcl` packages.




Structure
---------


Main areas (DejaGnu tools)
~~~~~~~~~~~~~~~~~~~~~~~~~~

The tests are grouped into different areas, called _tool_ in DejaGnu:

*install*:: 
  Functional tests for installation and caching of the main bash-completion package.
*completion*::
  Functional tests per completion.
*unit*:: 
  Unit tests for bash-completion helper functions.


Running the tests
~~~~~~~~~~~~~~~~~

The tests are run by calling `runtest` in the test directory:
-----------------------
runtest --outdir=log --tool completion
runtest --outdir=log --tool install
runtest --outdir=log --tool unit
-----------------------
The commands above are already wrapped up in shell scripts within the `test` directory:
-----------------------
./runCompletion
./runInstall
./runUnit
-----------------------




Maintenance
-----------


Adding a completion test
~~~~~~~~~~~~~~~~~~~~~~~~

You can add script/generate to add a test.




Rationale
---------


Naming conventions
~~~~~~~~~~~~~~~~~~

Test suite or testsuite
^^^^^^^^^^^^^^^^^^^^^^^
The primary Wikipedia page is called
http://en.wikipedia.org/wiki/Test_suite[test suite] and not testsuite, so that's what this
document sticks to.

script/generate
^^^^^^^^^^^^^^^
The name and location of this code generation script come from Ruby on Rails' http://en.wikibooks.org/wiki/Ruby_on_Rails/Tools/Generators[script/generate].




== Reference

Within test scripts the following library functions can be used:

== The test environment

The tests run in a specially prepared bash environment.  The following files are used:
* bashrch
* inputrc
* fixtures

=== bashrc

Contents of bashrc:

Index
=====
