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