diff options
Diffstat (limited to 'test/syscalls/README.md')
-rw-r--r-- | test/syscalls/README.md | 107 |
1 files changed, 0 insertions, 107 deletions
diff --git a/test/syscalls/README.md b/test/syscalls/README.md deleted file mode 100644 index 9e0991940..000000000 --- a/test/syscalls/README.md +++ /dev/null @@ -1,107 +0,0 @@ -# gVisor system call test suite - -This is a test suite for Linux system calls. It runs under both gVisor and -Linux, and ensures compatibility between the two. - -When adding support for a new syscall (or syscall argument) to gVisor, a -corresponding syscall test should be added. It's usually recommended to write -the test first and make sure that it passes on Linux before making changes to -gVisor. - -This document outlines the general guidelines for tests and specific rules that -must be followed for new tests. - -## Running the tests - -Each test file generates three different test targets that run in different -environments: - -* a `native` target that runs directly on the host machine, -* a `runsc_ptrace` target that runs inside runsc using the ptrace platform, and -* a `runsc_kvm` target that runs inside runsc using the KVM platform. - -For example, the test in `access_test.cc` generates the following targets: - -* `//test/syscalls:access_test_native` -* `//test/syscalls:access_test_runsc_ptrace` -* `//test/syscalls:access_test_runsc_kvm` - -Any of these targets can be run directly via `bazel test`. - -```bash -$ bazel test //test/syscalls:access_test_native -$ bazel test //test/syscalls:access_test_runsc_ptrace -$ bazel test //test/syscalls:access_test_runsc_kvm -``` - -To run all the tests on a particular platform, you can filter by the platform -tag: - -```bash -# Run all tests in native environment: -$ bazel test --test_tag_filters=native //test/syscalls/... - -# Run all tests in runsc with ptrace: -$ bazel test --test_tag_filters=runsc_ptrace //test/syscalls/... - -# Run all tests in runsc with kvm: -$ bazel test --test_tag_filters=runsc_kvm //test/syscalls/... -``` - -You can also run all the tests on every platform. (Warning, this may take a -while to run.) - -```bash -# Run all tests on every platform: -$ bazel test //test/syscalls/... -``` - -## Writing new tests - -Whenever we add support for a new syscall, or add support for a new argument or -option for a syscall, we should always add a new test (perhaps many new tests). - -In general, it is best to write the test first and make sure it passes on Linux -by running the test on the `native` platform on a Linux machine. This ensures -that the gVisor implementation matches actual Linux behavior. Sometimes man -pages contain errors, so always check the actual Linux behavior. - -gVisor uses the [Google Test][googletest] test framework, with a few custom -matchers and guidelines, described below. - -### Syscall matchers - -When testing an individual system call, use the following syscall matchers, -which will match the value returned by the syscall and the errno. - -```cc -SyscallSucceeds() -SyscallSucceedsWithValue(...) -SyscallFails() -SyscallFailsWithErrno(...) -``` - -### Use test utilities (RAII classes) - -The test utilties are written as RAII classes. These utilities should be -preferred over custom test harnesses. - -Local class instances should be preferred, wherever possible, over full test -fixtures. - -A test utility should be created when there is more than one test that requires -that same functionality, otherwise the class should be test local. - -## Save/Restore support in tests - -gVisor supports save/restore, and our syscall tests are written in a way to -enable saving/restoring at certain points. Hence, there are calls to -`MaybeSave`, and certain tests that should not trigger saves are named with -`NoSave`. - -However, the current open-source test runner does not yet support triggering -save/restore, so these functions and annotations have no effect on the tests. We -plan on extending the test runner to trigger save/restore. Until then, these -functions and annotations should be ignored. - -[googletest]: https://github.com/abseil/googletest |