Introduction
============
The tcplay tests use cucumber as test driver. Test cases are known as Scenarios
and are grouped by Feature.

The .feature files in features/ contain the Scenarios. What each step in a
scenario does is defined in the step_definitions files.



Running the tests
============
To run the tests, you first need to bootstrap the environment. Running the
following will install all required ruby gems:

    make bootstrap

You only have to do that once. After that, you can run tests using:

    make test

The tests must run as root, so sudo will prompt you for your password before
running the actual tests.

To be able to run the tests, you need to have 'libtcplay.so' and 'tcplay' in
the source directory. To get them, just change to the source directory and run

    make -f Makefile.classic clean all


Steps
============
The tcplay tests have the following step definitions, some of which use the command line
tool and some of which use the library (API):

* "Given I map volume <volume_name> as <map_name> using the following settings:"
* "Given I map volume <volume_name> as <map_name> with the API using the following settings:"

Where <volume_name> is a file name containing a volume and <map_name> is the
name of the mapped device.
The settings are specified in a table - the following are all possible settings:
passphrase              | Any passphrase
keyfiles                | path_to_kf1, path_to_kf2, ...
protect_hidden          | yes/no
passphrase_hidden       | Any passphrase
keyfiles_hidden         | path_to_kf1, path_to_kf2, ...
use_backup              | yes/no



* "Given I request information about volume <volume_name> using the following settings:"
* "Given I request information about volume <volume_name> with the API using the following settings:"

Where <volume_name> is a file name containing a volume.
The settings are specified in a table - the following are all possible settings:
passphrase              | Any passphrase
keyfiles                | path_to_kf1, path_to_kf2, ...
protect_hidden          | yes/no
passphrase_hidden       | Any passphrase
keyfiles_hidden         | path_to_kf1, path_to_kf2, ...
use_backup              | yes/no



* "Given I request information about mapped volume <map_name>"
* "Given I request information about mapped volume <map_name> with the API"

Where <map_name> is the mapped name of a volume previously mapped.



* "Given I create a volume <volume_name> of size <size_mb>M with the following parameters:"
* "Given I create a volume <volume_name> of size <size_mb>M using the API with the following parameters:"

Where <volume_name> is a file name that will be created to contain the newly
created volume. Its size will be <size_mb> MB.
The parameters are specified in a table - the following are all possible parameters:
passphrase              | Any passphrase
keyfiles                | path_to_kf1, path_to_kf2, ...
pbkdf_prf               | Any valid tcplay PBKDF PRF
cipher                  | Any valid tcplay cipher chain
create_hidden           | yes/no
hidden_mb               | A numeric size, e.g. 5.5 (meaning 5.5 MB)
passphrase_hidden       | Any passphrase
keyfiles_hidden         | path_to_kf1, path_to_kf2, ...
pbkdf_prf_hidden        | Any valid tcplay PBKDF PRF
cipher_hidden           | Any valid tcplay cipher chain



* "Given I modify volume <volume_name> using the following settings:"
* "Given I modify volume <volume_name> with the API using the following settings:"

Where <volume_name> is a file name containing a volume.
The settings are specified in a table - the following are all possible settings:
passphrase              | Any passphrase
keyfiles                | path_to_kf1, path_to_kf2, ...
new_passphrase          | Any passphrase
new_keyfiles            | path_to_kf1, path_to_kf2, ...
new_pbkdf_prf           | Any valid tcplay PBKDF PRF
use_backup              | yes/no



* "Given I modify volume <volume_name> by restoring from the backup header using the following settings:"

Where <volume_name> is a file name containing a volume.
The settings are specified in a table - the following are all possible settings:
passphrase              | Any passphrase
keyfiles                | path_to_kf1, path_to_kf2, ...



* "Then I expect dmsetup to have the following tables:"

The tables that should have been created by a previous "Given I map..." are
specified as a table with the following headers:
name                    | Name of the mapped volume
begin                   | First sector of the table
end                     | Last sector of the table
algo                    | Algorithm used for dm-crypt
key                     | The master key, in hexadecimal
offset                  | The offset on the raw device at which the volume starts
iv_offset               | The IV offset



* "Then I expect tcplay to report the following:"

The information tcplay should report after a previous "Given I request
information" is specified as a table with the following headers (which
are the same as the keys output by the --info command to tcplay):
PBKDF2 PRF              | Any valid tcplay PBKDF PRF
PBKDF2 iterations       | A numeric value
Cipher                  | Any valid tcplay cipher chain
Key Length              | A string such as "512 bits"
CRC Key Data            | A hexadecimal value such as "0xdeadc0de"
Sector size             | A numeric value such as 512
Volume size             | A string such as "40448 sectors"
IV offset               | A numeric value (in blocks)
Block offset            | A numeric value (in blocks)

The output of the API information request has the following fields
instead:
PBKDF2 PRF              | Any valid tcplay PBKDF PRF
Cipher                  | Any valid tcplay cipher chain
Key Length              | A string such as "512 bits"
Volume size             | A string such as "20709376 bytes"
IV offset               | A string such as "131072 bytes"
Block offset            | A string such as "131072 bytes"

The "Given I request information about mapped volume" steps will
generate the same information, except the PBKDF2 and CRC Key Data
fields will be missing.



* "Then I expect tcplay to succeed"



* "Then I expect tcplay to fail"
