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