github.com/cilium/cilium@v1.16.2/Documentation/contributing/testing/unit.rst (about)

     1  .. only:: not (epub or latex or html)
     2  
     3      WARNING: You are looking at unreleased Cilium documentation.
     4      Please use the official rendered version released here:
     5      https://docs.cilium.io
     6  
     7  .. _integration_testing:
     8  
     9  Integration Testing
    10  ===================
    11  
    12  Cilium uses the standard `go test <https://golang.org/pkg/testing/>`__ framework.
    13  All new tests must use `the standard test framework`_.
    14  
    15  .. _the standard test framework: https://github.com/cilium/cilium/issues/16860
    16  
    17  .. _integration_testing_prerequisites:
    18  
    19  Prerequisites
    20  ^^^^^^^^^^^^^
    21  
    22  Some tests interact with the kvstore and depend on a local kvstore instances of
    23  etcd. To start the local instances, run:
    24  
    25  .. code-block:: shell-session
    26  
    27       $ make start-kvstores
    28  
    29  Running all tests
    30  ^^^^^^^^^^^^^^^^^
    31  
    32  To run integration tests over the entire repository, run the following command
    33  in the project root directory:
    34  
    35  .. code-block:: shell-session
    36  
    37      $ make integration-tests
    38  
    39  To run just unit tests, run:
    40  
    41  .. code-block:: shell-session
    42  
    43      $ go test ./...
    44  
    45  Testing individual packages
    46  ^^^^^^^^^^^^^^^^^^^^^^^^^^^
    47  
    48  It is possible to test individual packages by invoking ``go test`` directly.
    49  You can then ``cd`` into the package subject to testing and invoke go test:
    50  
    51  .. code-block:: shell-session
    52  
    53      $ cd pkg/kvstore
    54      $ go test
    55  
    56  Integration tests have some prerequisites like
    57  :ref:`integration_testing_prerequisites`, you can use the following command to
    58  automatically set up the prerequisites, run the unit tests and tear down the
    59  prerequisites:
    60  
    61  .. code-block:: shell-session
    62  
    63      $ make integration-tests TESTPKGS=./pkg/kvstore
    64  
    65  Some tests are marked as 'privileged' if they require the test suite to be run
    66  as a privileged user or with a given set of capabilities. They are skipped by
    67  default when running ``go test``.
    68  
    69  There are a few ways to run privileged tests.
    70  
    71  1. Run the whole test suite with sudo.
    72  
    73      .. code-block:: shell-session
    74  
    75          $ sudo make tests-privileged
    76  
    77  2. To narrow down the packages under test, specify ``TESTPKGS``. Note that this
    78     takes the Go package pattern syntax, including ``...`` wildcard specifier.
    79  
    80      .. code-block:: shell-session
    81  
    82          $ sudo make tests-privileged TESTPKGS="./pkg/datapath/linux ./pkg/maps/..."
    83  
    84  3. Set the ``PRIVILEGED_TESTS`` environment variable and run ``go test``
    85     directly. This only escalates privileges when executing the test binaries,
    86     the ``go build`` process is run unprivileged.
    87  
    88      .. code-block:: shell-session
    89  
    90          $ PRIVILEGED_TESTS=true go test -exec "sudo -E" ./pkg/ipam
    91  
    92  Automatically run unit tests on code changes
    93  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    94  
    95  The script ``contrib/shell/test.sh`` contains some helpful bash functions to
    96  improve the feedback cycle between writing tests and seeing their results. If
    97  you're writing unit tests in a particular package, the ``watchtest`` function
    98  will watch for changes in a directory and run the unit tests for that package
    99  any time the files change. For example, if writing unit tests in ``pkg/policy``,
   100  run this in a terminal next to your editor:
   101  
   102  .. code-block:: shell-session
   103  
   104      $ . contrib/shell/test.sh
   105      $ watchtest pkg/policy
   106  
   107  This shell script depends on the ``inotify-tools`` package on Linux.