1Linux Test Project 2================== 3 4Linux Test Project is a joint project started by SGI, OSDL and Bull developed 5and maintained by IBM, Cisco, Fujitsu, SUSE, Red Hat, Oracle and others. The 6project goal is to deliver tests to the open source community that validate the 7reliability, robustness, and stability of Linux. 8 9The LTP testsuite contains a collection of tools for testing the Linux kernel 10and related features. Our goal is to improve the Linux kernel and system 11libraries by bringing test automation to the testing effort. Interested open 12source contributors are encouraged to join. 13 14Project pages are located at: http://linux-test-project.github.io/ 15 16The latest image is always available at: 17https://github.com/linux-test-project/ltp/releases 18 19The discussion about the project happens at LTP mailing list: 20http://lists.linux.it/listinfo/ltp 21 22LTP mailing list is archived at: 23https://lore.kernel.org/ltp/ 24 25IRC #ltp at: [irc.libera.chat](https://libera.chat/) 26 27The git repository is located at GitHub at: 28https://github.com/linux-test-project/ltp 29 30The patchwork instance is at: 31https://patchwork.ozlabs.org/project/ltp/list/ 32 33Warning! 34======== 35 36**Be careful with these tests!** 37 38Don't run them on production systems. Growfiles, doio, and iogen in particular 39stress the I/O capabilities of systems and while they should not cause problems 40on properly functioning systems, they are intended to find (or cause) problems. 41 42Quick guide to running the tests 43================================ 44 45If you have git, autoconf, automake, m4, pkgconf / pkg-config, libc headers, 46linux kernel headers and other common development packages installed (see 47INSTALL and ci/*.sh), the chances are the following will work: 48 49``` 50$ git clone https://github.com/linux-test-project/ltp.git 51$ cd ltp 52$ make autotools 53$ ./configure 54``` 55 56Now you can continue either with compiling and running a single test or with 57compiling and installing the whole testsuite. 58 59For optional library dependencies look into scripts for major distros in 60`ci/` directory. You can also build whole LTP with `./build.sh` script. 61 62Shortcut to running a single test 63--------------------------------- 64If you need to execute a single test you actually do not need to compile 65the whole LTP, if you want to run a syscall testcase following should work. 66 67``` 68$ cd testcases/kernel/syscalls/foo 69$ make 70$ PATH=$PATH:$PWD ./foo01 71``` 72 73Shell testcases are a bit more complicated since these need a path to a shell 74library as well as to compiled binary helpers, but generally following should 75work. 76 77``` 78$ cd testcases/lib 79$ make 80$ cd ../commands/foo 81$ PATH=$PATH:$PWD:$PWD/../../lib/ ./foo01.sh 82``` 83 84Open Posix Testsuite has it's own build system which needs Makefiles to be 85generated first, then compilation should work in subdirectories as well. 86 87``` 88$ cd testcases/open_posix_testsuite/ 89$ make generate-makefiles 90$ cd conformance/interfaces/foo 91$ make 92$ ./foo_1-1.run-test 93``` 94 95Compiling and installing all testcases 96-------------------------------------- 97 98``` 99$ make 100$ make install 101``` 102 103This will install LTP to `/opt/ltp`. 104* If you have a problem see `doc/mini-howto-building-ltp-from-git.txt`. 105* If you still have a problem see `INSTALL` and `./configure --help`. 106* Failing that, ask for help on the mailing list or Github. 107 108Some tests will be disabled if the configure script can not find their build 109dependencies. 110 111* If a test returns `TCONF` due to a missing component, check the `./configure` 112 output. 113* If a tests fails due to a missing user or group, see the Quick Start section 114 of `INSTALL`. 115 116Running tests 117------------- 118 119To run all the test suites 120 121``` 122$ cd /opt/ltp 123$ ./runltp 124``` 125 126Note that many test cases have to be executed as root. 127 128To run a particular test suite 129 130``` 131$ ./runltp -f syscalls 132``` 133 134To run all tests with `madvise` in the name 135 136``` 137$ ./runltp -f syscalls -s madvise 138``` 139Also see 140 141``` 142$ ./runltp --help 143``` 144 145Test suites (e.g. syscalls) are defined in the runtest directory. Each file 146contains a list of test cases in a simple format, see doc/ltp-run-files.txt. 147 148Each test case has its own executable or script, these can be executed 149directly 150 151``` 152$ testcases/bin/abort01 153``` 154 155Some have arguments 156 157``` 158$ testcases/bin/mesgq\_nstest -m none 159``` 160 161The vast majority of test cases accept the -h (help) switch 162 163``` 164$ testcases/bin/ioctl01 -h 165``` 166 167Many require certain environment variables to be set 168 169``` 170$ LTPROOT=/opt/ltp PATH="$PATH:$LTPROOT/testcases/bin" testcases/bin/wc01.sh 171``` 172 173Most commonly, the path variable needs to be set and also `LTPROOT`, but there 174are a number of other variables, `runltp` usually sets these for you. 175 176Note that all shell scripts need the `PATH` to be set. However this is not 177limited to shell scripts, many C based tests need environment variables as 178well. 179 180For more info see `doc/user-guide.txt` or online at 181https://github.com/linux-test-project/ltp/wiki/User-Guidelines. 182 183Network tests 184------------- 185Network tests require certain setup, described in `testcases/network/README.md` 186(online at https://github.com/linux-test-project/ltp/tree/master/testcases/network). 187 188Developers corner 189================= 190 191Before you start you should read following documents: 192 193* `doc/test-writing-guidelines.txt` 194* `doc/build-system-guide.txt` 195* `doc/library-api-writing-guidelines.txt` 196 197There is also a step-by-step tutorial: 198 199* `doc/c-test-tutorial-simple.txt` 200 201If something is not covered there don't hesitate to ask on the LTP mailing 202list. Also note that these documents are available online at: 203 204* https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines 205* https://github.com/linux-test-project/ltp/wiki/LTP-Library-API-Writing-Guidelines 206* https://github.com/linux-test-project/ltp/wiki/Build-System 207* https://github.com/linux-test-project/ltp/wiki/C-Test-Case-Tutorial 208 209Although we accept GitHub pull requests, the preferred way is sending patches to our mailing list. 210 211It's a good idea to test patches on GitHub Actions before posting to mailing 212list. Our GitHub Actions setup covers various architectures and distributions in 213order to make sure LTP compiles cleanly on most common configurations. 214For testing you need to just push your changes to your own LTP fork on GitHub. 215