gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/test/syscalls/README.md (about)

     1  # gVisor system call test suite
     2  
     3  This is a test suite for Linux system calls. It runs under both gVisor and
     4  Linux, and ensures compatibility between the two.
     5  
     6  When adding support for a new syscall (or syscall argument) to gVisor, a
     7  corresponding syscall test should be added. It's usually recommended to write
     8  the test first and make sure that it passes on Linux before making changes to
     9  gVisor.
    10  
    11  This document outlines the general guidelines for tests and specific rules that
    12  must be followed for new tests.
    13  
    14  ## Running the tests
    15  
    16  Each test file generates three different test targets that run in different
    17  environments:
    18  
    19  *   a `native` target that runs directly on the host machine
    20  *   a `runsc_systrap` target that runs inside runsc using the systrap platform
    21  *   a `runsc_ptrace` target that runs inside runsc using the ptrace platform
    22  *   a `runsc_kvm` target that runs inside runsc using the KVM platform.
    23  
    24  For example, the test in `access_test.cc` generates the following targets:
    25  
    26  *   `//test/syscalls:access_test_native`
    27  *   `//test/syscalls:access_test_runsc_systrap`
    28  *   `//test/syscalls:access_test_runsc_ptrace`
    29  *   `//test/syscalls:access_test_runsc_kvm`
    30  
    31  Any of these targets can be run directly via `bazel test`.
    32  
    33  ```bash
    34  $ bazel test //test/syscalls:access_test_native
    35  $ bazel test //test/syscalls:access_test_runsc_systrap
    36  $ bazel test //test/syscalls:access_test_runsc_ptrace
    37  $ bazel test //test/syscalls:access_test_runsc_kvm
    38  ```
    39  
    40  To run all the tests on a particular platform, you can filter by the platform
    41  tag:
    42  
    43  ```bash
    44  # Run all tests in native environment:
    45  $ bazel test --test_tag_filters=native //test/syscalls/...
    46  
    47  # Run all tests in runsc with systrap:
    48  $ bazel test --test_tag_filters=runsc_systrap //test/syscalls/...
    49  
    50  # Run all tests in runsc with ptrace:
    51  $ bazel test --test_tag_filters=runsc_ptrace //test/syscalls/...
    52  
    53  # Run all tests in runsc with kvm:
    54  $ bazel test --test_tag_filters=runsc_kvm //test/syscalls/...
    55  ```
    56  
    57  You can also run all the tests on every platform. (Warning, this may take a
    58  while to run.)
    59  
    60  ```bash
    61  # Run all tests on every platform:
    62  $ bazel test //test/syscalls/...
    63  ```
    64  
    65  ## Writing new tests
    66  
    67  Whenever we add support for a new syscall, or add support for a new argument or
    68  option for a syscall, we should always add a new test (perhaps many new tests).
    69  
    70  In general, it is best to write the test first and make sure it passes on Linux
    71  by running the test on the `native` platform on a Linux machine. This ensures
    72  that the gVisor implementation matches actual Linux behavior. Sometimes man
    73  pages contain errors, so always check the actual Linux behavior.
    74  
    75  gVisor uses the [Google Test][googletest] test framework, with a few custom
    76  matchers and guidelines, described below.
    77  
    78  ### Syscall matchers
    79  
    80  When testing an individual system call, use the following syscall matchers,
    81  which will match the value returned by the syscall and the errno.
    82  
    83  ```cc
    84  SyscallSucceeds()
    85  SyscallSucceedsWithValue(...)
    86  SyscallFails()
    87  SyscallFailsWithErrno(...)
    88  ```
    89  
    90  ### Use test utilities (RAII classes)
    91  
    92  The test utilties are written as RAII classes. These utilities should be
    93  preferred over custom test harnesses.
    94  
    95  Local class instances should be preferred, wherever possible, over full test
    96  fixtures.
    97  
    98  A test utility should be created when there is more than one test that requires
    99  that same functionality, otherwise the class should be test local.
   100  
   101  ## Save/Restore support in tests
   102  
   103  gVisor supports save/restore, and our syscall tests are written in a way to
   104  enable saving/restoring at certain points. Hence, there are calls to
   105  `MaybeSave`, and certain tests that should not trigger saves are named with
   106  `NoSave`.
   107  
   108  However, the current open-source test runner does not yet support triggering
   109  save/restore, so these functions and annotations have no effect on the tests. We
   110  plan on extending the test runner to trigger save/restore. Until then, these
   111  functions and annotations should be ignored.
   112  
   113  [googletest]: https://github.com/abseil/googletest