CI test fixtures — pyroute2 0.9.4 documentation

# CI test fixtures

Added in version 0.9.1.

The library provides a set of fixtures that can be used with pytest to setup a simple test environment for functional network tests.

Usage:

    # file: conftest.py
    pytest_plugins = [
        'pyroute2.fixtures.iproute',
        'pyroute2.fixtures.ndb',
        'pyroute2.fixtures.plan9'
    ]

    # file: my_test.py
    def test_my_code(sync_context):
        # here you have access to
        #
        sync_context.ipr        # IPRoute instance running in a netns
        sync_context.netns      # ready to use netns with a test link up
        sync_context.test_link  # test link in the netns
        sync_context.test_link.index    # interface index
        sync_context.test_link.ifname   # interface name
        sync_context.test_link.address  # MAC address

The fixtures set up a network namespace with a unique name, a dummy interface within the namespace, and bring the interface up. They form a tree of dependencies, so if you use e.g. test_link_ifname fixture, you may be sure that the namespace and the interface are already set up properly.

Fixtures dependencies diagram:

pyroute2.fixtures.iproute.nsname() → Generator[str]

  Network namespace.

  - Name: nsname

  - Scope: function

  Create a unique network namespace and yield its name. Remove the netns on cleanup.

  It’s safe to create and modify interfaces, addresses, routes etc. in the test network namespace, as it is disconnected from the main system, and the test cleanup will remove the namespace with all its content.

  Example usage:

      def test_list_interfaces(nsname):
          subprocess.Popen(
              ['ip', 'netns', 'exec', nsname, 'ip', 'link'],
              stdout=subprocess.PIPE,
          )
          # ...

pyroute2.fixtures.iproute.test_link_ifinfmsg(nsname: str) → Generator[ifinfmsg]

  Test interface ifinfmsg.

  - Name: test_link_ifinfmsg

  - Scope: function

  - Depends: nsname

  Create a test interface in the test netns and yield ifinfmsg. Remove the interface on cleanup.

  This fixture depends on nsname, and it means that the network namespace will be created automatically if you use this fixture.

  Example usage:

      def test_check_interface(nsname, test_link_ifinfmsg):
          link = test_link_ifinfmsg
          ns = ['ip', 'netns', 'exec', nsname]
          up = ['ip', 'link', 'set', 'dev', link.get('ifname'), 'up']
          subprocess.Popen(ns + up)
          # ...

pyroute2.fixtures.iproute.test_link(nsname: str, test_link_ifinfmsg: ifinfmsg) → Generator[TestInterface]

  Test interface spec.

  - Name: test_link

  - Scope: function

  - Depends: nsname, test_link_ifinfmsg

  Yield TestInterface object for the test interface, providing a convenient way to access some important interface properties.

pyroute2.fixtures.iproute.test_link_address(test_link: TestInterface) → Generator[str]

  Test interface MAC address.

  - Name: test_link_address

  - Scope: function

  - Depends: test_link

  Yield test interface MAC address. The network namespace and the test interface exist at this point.

pyroute2.fixtures.iproute.test_link_index(test_link: TestInterface) → Generator[int]

  Test interface MAC index.

  - Name: test_link_index

  - Scope: function

  - Depends: test_link

  Yield test interface index. The network namespace and the test interface exist at this point.

pyroute2.fixtures.iproute.test_link_ifname(test_link: TestInterface) → Generator[str]

  Test interface MAC ifname.

  - Name: test_link_ifname

  - Scope: function

  - Depends: test_link

  Yield test interface ifname. The network namespace and the test interface exist at this point.

pyroute2.fixtures.iproute.async_ipr(request, nsname: str) → AsyncGenerator[AsyncIPRoute]

  AsyncIPRoute instance.

  - Name: async_ipr

  - Scope: function

  - Depends: nsname

  Yield AsyncIPRoute instance, running within the test network namespace. You can provide additional keyword arguments to AsyncIPRoute:

      @pytest.mark.parametrize(
          'async_ipr',
          [
              {
                  'ext_ack': True,
                  'strict_check': True,
              },
          ],
          indirect=True
      )
      @pytest.mark.asyncio
      async def test_my_case(async_ipr):
          await async_ipr.link('set', index=1, state='up')

pyroute2.fixtures.iproute.sync_ipr(request, nsname: str) → Generator[IPRoute]

  IPRoute instance.

  - Name: sync_ipr

  - Scope: function

  - Depends: nsname

  Yield IPRoute instance, running within the test network namespace. You can provide additional keyword arguments to IPRoute:

      @pytest.mark.parametrize(
          'sync_ipr',
          [
              {
                  'ext_ack': True,
                  'strict_check': True,
              },
          ],
          indirect=True
      )
      def test_my_case(sync_ipr):
          sync_ipr.link('set', index=1, state='up')

pyroute2.fixtures.iproute.async_context(async_ipr: AsyncIPRoute, test_link: TestInterface) → AsyncGenerator[TestContext[AsyncIPRoute]]

  Asynchronous TestContext.

  - Name: async_context

  - Scope: function

  - Depends: async_ipr, test_link

  Yield TestContext with AsyncIPRoute.

pyroute2.fixtures.iproute.sync_context(sync_ipr: IPRoute, test_link: TestInterface) → Generator[TestContext[IPRoute]]

  Synchronous TestContext.

  - Name: sync_context

  - Scope: function

  - Depends: sync_ipr, test_link

  Yield TestContext with IPRoute.

pyroute2.fixtures.ndb.ndb(nsname: str) → Generator[NDB]

  NDB instance.

  - Name: ndb

  - Scope: function

  - Depends: nsname

  Yield NDB instance running in the test network namespace.

class pyroute2.fixtures.iproute.TestInterface(index: int, ifname: str, address: str, nsname: str)

  Test interface spec.

  Provided by test_link fixture.

  Provides shortcuts to some important interface properties, like TestInterface.index or TestInterface.netns.

  property index: int

    Test interface index.

    Is always greater than 1, as index 1 has the the loopback interface.

  property ifname: str

    Test interface ifname.

    The name length must be greater than 1 and less or equal IFNAMSIZ.

  property address: str

    Test interface MAC address.

    In the form xx:xx:xx:xx:xx:xx.

  property netns: str

    Test interface netns.

    A string name of the network namespace.

class pyroute2.fixtures.iproute.TestContext(ipr: T, test_link: TestInterface)

  The test context.

  Provided by async_context and sync_context fixtures.

  Provides convenient shortcuts to RTNL API, the network namespace name and the test interface spec.

  property ipr: T

    RTNL API.

    Return RTNL API instance, either IPRoute, or AsyncIPRoute.

  property test_link: TestInterface

    Test interface spec.

    Return TestInterface object for the test interface.

  property netns: str

    Network namespace.

    A string name of the network namespace.