| 1 |
sndfile-regtest |
| 2 |
=============== |
| 3 |
|
| 4 |
The 'sndfile-regtest' program is a regression test-suite for libsndile. |
| 5 |
|
| 6 |
This program is intended to allow anyone who has an interest in the |
| 7 |
reliability and correctness of libsndfile to do their own regression |
| 8 |
testing. From the point of view of the libsndfile developers, this |
| 9 |
program now allows for distributed regression testing of libsndfile |
| 10 |
which will make libsndfile better. |
| 11 |
|
| 12 |
|
| 13 |
How Does it Work |
| 14 |
---------------- |
| 15 |
Anyone who wishes to take part in the distributed regression testing of |
| 16 |
libsndfile can download the regression test program and install it. |
| 17 |
|
| 18 |
Once installed the user can start collecting files and adding them to |
| 19 |
their own personal database. Then, as new versions of libsndfile come |
| 20 |
out, the user should test the new library version against their database |
| 21 |
of files (instructions below). |
| 22 |
|
| 23 |
Any files which were successfully added to the database in the past but |
| 24 |
now fail the check with the new library version represent a regression. |
| 25 |
The user should then contact the libsndfile developers so that a copy |
| 26 |
of the test file can be made available to the developers. |
| 27 |
|
| 28 |
|
| 29 |
Requirements |
| 30 |
------------ |
| 31 |
The regression test program uses sqlite3 as the database engine. On |
| 32 |
Debian, the required packages are : |
| 33 |
|
| 34 |
sqlite3 |
| 35 |
libsqlite3-0 |
| 36 |
libsqlite3-dev |
| 37 |
|
| 38 |
but similar packages should be available on any other Linux style |
| 39 |
system. |
| 40 |
|
| 41 |
The regression test currently only compiles under Unix-like systems. |
| 42 |
At some time in the future the regression test will distributed along |
| 43 |
with the libsndfile source code distribution. |
| 44 |
|
| 45 |
|
| 46 |
Organization of Files |
| 47 |
--------------------- |
| 48 |
The regession test program keeps its database file in the directory it |
| 49 |
is run from. In addition, the database only contains information about |
| 50 |
the files, not the files themselves. |
| 51 |
|
| 52 |
This means that database file should probably be kept in the same |
| 53 |
directory (or a directory above) the test files. |
| 54 |
|
| 55 |
|
| 56 |
Setting it Up for the First Time |
| 57 |
-------------------------------- |
| 58 |
The sndfile-regtest program should be on your PATH. You can then cd into |
| 59 |
the directory where you intend to keep you test files and |
| 60 |
run the command: |
| 61 |
|
| 62 |
sndfile-regtest --create-db |
| 63 |
|
| 64 |
which creates a file named '.sndfile-regtest.db' in the current directory. |
| 65 |
|
| 66 |
Files can then be added to the database using the command: |
| 67 |
|
| 68 |
sndfile-regtest --add-file file1.wav |
| 69 |
|
| 70 |
The --add-file option allows more than one file to be added at a time |
| 71 |
using: |
| 72 |
|
| 73 |
sndfile-regtest --add-file file1.wav file2.aif ..... |
| 74 |
|
| 75 |
|
| 76 |
Checking Files |
| 77 |
-------------- |
| 78 |
One or more files that have already been added to the database can be |
| 79 |
checked using: |
| 80 |
|
| 81 |
sndfile-regtest --check-file file1.wav file2.aif ..... |
| 82 |
|
| 83 |
It is also possible to check all files in the database using: |
| 84 |
|
| 85 |
sndfile-regtest --check-all |
| 86 |
|
| 87 |
|
| 88 |
Running a Regression Test |
| 89 |
------------------------- |
| 90 |
Once you have a collection of files and a database it is possible to test |
| 91 |
new versions of libsndfile before you install them. If for instance you |
| 92 |
have just compiled a new version of libsndfile in the directory |
| 93 |
/usr/src/libsndfile-X.Y.Z, then you can use an existing sndfile-regtest |
| 94 |
binary with the new libsndfile using something like: |
| 95 |
|
| 96 |
LD_PRELOAD=/usr/src/libsndfile-X.Y.Z/src/.libs/libsndfile.so.X.Y.Z \ |
| 97 |
sndfile-regtest --check-all |
| 98 |
|
| 99 |
|
| 100 |
Reporting Regressions |
| 101 |
--------------------- |
| 102 |
Any user who finds a file which was added to the regression database with |
| 103 |
an earlier version of libsndfile and then fails the check with a later |
| 104 |
version of the library should contact the author (erikd at mega dash nerd |
| 105 |
dot com). If possible place the file on a web server and email the author |
| 106 |
a link to it. |
| 107 |
|
| 108 |
|