trunk/grubby/README.rst

grubby is a command line tool for updating and displaying information about
the configuration files for the grub, lilo, elilo (ia64), yaboot (powerpc)
and zipl (s390) boot loaders. It is primarily designed to be used from scripts
which install new kernels and need to find information about the current boot
environment.


Testing grubby
==============

To execute the integrated test suite from inside the source directory run the
command::

    make test


Test Suite Architecture
------------------------

grubby's test suite is written in Bash. The file `test.sh` contains several
helper functions and a list of different test scenarios which are exercised
upon execution. Important functions are:

- oneTest() - test if the configuration generated by the supplied grubby
  parameters matches a well known configuration file;

- oneDisplayTest() - test grubby features that display some information,
  checking grubby's output against well known values;

- commandTest() - test if the output of some commands matches the provided
  text. This function is only used for grub2 testing in a few places.


Note: the test suite creates aliases for oneTest() and oneDisplayTest(), which
are prefixed with the corresponding boot loader name. For example:
grubTest(). eliloTest(), etc.

The invocation syntax is::

    testFunction config_file results_file --grubby --options

For example the line::

    grubTest grub.1 updargs/g1.1 --update-kernel=DEFAULT --args="root=/dev/hda1"

means execute the command::

    ./grubby --grub --config-file tests/grub.1 --update-kernel=DEFAULT \
    --args="root=/dev/hda1"

and compare the resulting configuration with the file
`tests/results/updargs/g1.1`.


The line::

    grubDisplayTest grub.1 defaultindex/0 --default-index

means execute::

    ./grubby --grub --config-file tests/grub.1 --default-index

and compare the output with the file `tests/results/defaultindex/0`.

Writing New Test Cases
----------------------

To write a new test case for grubby you need a config file which matches the
initial test conditions (either existing one or a new one), provide a
results file (likely a new one) which contains the expected configuration or
output and finally add a call to the test function(s) using the desired grubby
parameters in an appropriate section of `test.sh`.
1	niro	2987	grubby is a command line tool for updating and displaying information about
2			the configuration files for the grub, lilo, elilo (ia64), yaboot (powerpc)
3			and zipl (s390) boot loaders. It is primarily designed to be used from scripts
4			which install new kernels and need to find information about the current boot
5			environment.
6
7
8			Testing grubby
9			==============
10
11			To execute the integrated test suite from inside the source directory run the
12			command::
13
14			make test
15
16
17			Test Suite Architecture
18			------------------------
19
20			grubby's test suite is written in Bash. The file `test.sh` contains several
21			helper functions and a list of different test scenarios which are exercised
22			upon execution. Important functions are:
23
24			- oneTest() - test if the configuration generated by the supplied grubby
25			parameters matches a well known configuration file;
26
27			- oneDisplayTest() - test grubby features that display some information,
28			checking grubby's output against well known values;
29
30			- commandTest() - test if the output of some commands matches the provided
31			text. This function is only used for grub2 testing in a few places.
32
33
34			Note: the test suite creates aliases for oneTest() and oneDisplayTest(), which
35			are prefixed with the corresponding boot loader name. For example:
36			grubTest(). eliloTest(), etc.
37
38			The invocation syntax is::
39
40			testFunction config_file results_file --grubby --options
41
42			For example the line::
43
44			grubTest grub.1 updargs/g1.1 --update-kernel=DEFAULT --args="root=/dev/hda1"
45	niro	2988
46	niro	2987	means execute the command::
47
48			./grubby --grub --config-file tests/grub.1 --update-kernel=DEFAULT \
49			--args="root=/dev/hda1"
50
51			and compare the resulting configuration with the file
52			`tests/results/updargs/g1.1`.
53
54
55			The line::
56
57			grubDisplayTest grub.1 defaultindex/0 --default-index
58
59			means execute::
60
61			./grubby --grub --config-file tests/grub.1 --default-index
62
63			and compare the output with the file `tests/results/defaultindex/0`.
64
65			Writing New Test Cases
66			----------------------
67
68			To write a new test case for grubby you need a config file which matches the
69	niro	2988	initial test conditions (either existing one or a new one), provide a
70	niro	2987	results file (likely a new one) which contains the expected configuration or
71			output and finally add a call to the test function(s) using the desired grubby
72			parameters in an appropriate section of `test.sh`.