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