Test Setup Examples
===================

Static org - Auth enrollment
----------------------------

This example shows how to define a WAFT test that will install WARP
and enroll the test system in the "AutoWARP" organization
using auth token enrollment before the test begins.

.. code-block:: python
    :linenos:

    import pytest

    import waft

    from waft import fixture


    @waft.mark.warp_zero_trust(organization='AutoWARP')
    def test_example(warp: fixture.warp):
        """This test definition serves as an example of how to
        define a test that will enroll the test system in a
        static organization using token authentication.
        """


Static org - Email enrollment
-----------------------------

This example shows how to define a WAFT test that will install WARP
and enroll the test system in the "AutoWARP" organization
using email enrollment before the test begins.

.. code-block:: python
    :linenos:

    import pytest

    import waft

    from waft import fixture


    @waft.mark.warp_zero_trust(organization='AutoWARP', enroll='identity')
    def test_example(warp: fixture.warp):
        """This test definition serves as an example of how to
        define a test that will enroll the test system in a
        static organization using email authentication.
        """


Single Device Profile
---------------------

This example shows how to define a WAFT test that only needs a single device profile
to do testing (no actions are needed to be taken outside that single device profile).
WARP will be installed and then the device will be enrolled using email
(to specify device profile) in the org that is reserved for single device profile tests.

.. code-block:: python
    :linenos:

    import pytest

    import waft

    from waft import fixture


    # This marker is still used since the test will be testing the zero trust product.
    @waft.mark.warp_zero_trust()
    def test_example(warp: fixture.warp, single_device_profile: fixture.single_device_profile):
        """This test definition serves as an example of how to
        define a test that will enroll the test system in a
        static organization using email authentication
        and a custom device profile.

        1. Device profile created for the test will be accessible
        through the `single_device_profile` fixture.
        """


Dynamic Organization - Auth enrollment
--------------------------------------

This example shows how to define a WAFT test that will use a dynamic organization
and enroll by Auth token.
These are organizations that are maintained in a nominal state before being used for tests.

.. code-block:: python
    :linenos:

    import pytest
    import waft

    from waft import fixture


    @waft.mark.warp_zero_trust(dynamic=True)
    def test_example(warp: fixture.warp, dashboard: fixture.dashboard):
        """This test definition serves as an example of how to
        define a test that will enroll the test system in a
        dynamically allocated organization using token authentication.

        1. The dynamic organization will be reserved solely
           for this test for the duration of its execution.

        2. Dashboard functionality for the organization will be accessible
           through the `dashboard` fixture.
        """


Dashboard - Cloudflare API
--------------------------

WAFT offers complete access to Cloudflare's products and services
via the `Cloudflare API <https://developers.cloudflare.com/api/resources/zero_trust/>`_.
The `Cloudflare Python SDK <https://github.com/cloudflare/cloudflare-python/blob/main/api.md#zerotrust>`_
can be invoked directly from the `dashboard` fixture via its `client` attribute
or indirectly via the additional properties and methods it provides to automate common actions.

.. code-block:: python
    :linenos:

    import pytest

    import waft

    from waft import fixture


    @waft.mark.warp_zero_trust(dynamic=True)
    def test_example(dashboard: fixture.dashboard):
        """This test definition serves as an example of how to
        define a test that will access Cloudflare dashboard functionality.

        1. The dynamic organization will be reserved solely
           for this test for the duration of its execution.

        2. Dashboard functionality for the organization will be accessible
           through the `dashboard` fixture.
        """
        # Form 1: Fetch list of device posture rules - from the SDK directly
        posture_rules = dashboard.client.zero_trust.devices.posture.list(account_id=dashboard.account_id)

        # Form 2: Fetch list of device posture rules - using WAFT helper method
        posture_rules = dashboard.list(dashboard.client.zero_trust.devices.posture)

        # Store a single device posture rule ID
        posture_rule = posture_rules[0]

        # Fetch list of matching device posture rules - using WAFT helper method
        matching_rules = dashboard.search(dashboard.client.zero_trust.devices.posture, name=posture_rule.name)

        # Form 1: Fetch a single device posture rule - from the SDK directly
        rule_info = dashboard.client.zero_trust.devices.posture.get(posture_rule.id, account_id=dashboard.account_id)

        # Form 2: Fetch a single device posture rule - using WAFT helper method
        rule_info = dashboard.get(dashboard.client.zero_trust.devices.posture, posture_rule.id)

        # Form 3: Fetch a single device posture rule - using available WAFT action method
        rule_info = dashboard.device_posture.get_rule(posture_rule.id)


Platforms - Allow
-----------------

Although WAFT tests are typically designed to run with all supported platforms,
there may be exceptions to that rule.
This example shows how to define a WAFT test that should be run with particular platform(s)
and/or operating system version(s), exclusively.
The test will be skipped for all other platforms and operating systems,
with the platform limitation reported as the reason.

.. code-block:: python
    :linenos:

    import pytest
    import waft

    from waft import fixture


    @waft.mark.platform(waft.mark.Platforms.MACOS)
    @waft.mark.platform(waft.mark.Platforms.WINDOWS, codename='24H2', version='11')
    @waft.mark.platform(waft.mark.Platforms.UBUNTU, version='25')
    @waft.mark.platform(waft.mark.Platforms.UBUNTU, codename='noble')
    @waft.mark.platform(waft.mark.Platforms.UBUNTU, codename='jammy')
    def test_example():
        """This test definition serves as an example of how to
        define a test that will run exclusively on any macOS version,
        Windows 11 version 24H2, and Ubuntu versions 25, Noble Numbat,
        or Jammy Jellyfish.
        """


Platforms - Skip
----------------

This example shows how to define a WAFT test that should NOT be run
with particular platform(s) and/or operating system version(s).
The test will be skipped for all marked platforms and operating systems,
with the platform limitation reported as the reason.

.. code-block:: python
    :linenos:

    import pytest
    import waft

    from waft import fixture

    @waft.mark.platform_skip(waft.mark.Platforms.CENTOS)
    @waft.mark.platform_skip(waft.mark.Platforms.MACOS, version='12')
    @waft.mark.platform_skip(waft.mark.Platforms.MACOS, codename='ventura')
    def test_example():
        """This test definition serves as an example of how to
        define a test that will run on all platforms,
        except CentOS, macOS versions 12 and Ventura.
        """


Defects
-------

This example shows how to define a WAFT test that is affected by a JIRA reported defect.
The `defect` marker:
 - logs the defect as an error message
 - logs a warning message with optional additional details
 - tags the test with a `defect` label in the Allure report
 - inserts a link to the JIRA defect in the Allure report
 - does not alter test execution
 - can be expressed statically (unconditionally) as a decorator
 - can be expressed dynamically (conditionally) as a function call
 - can be paired with `standard pytest markers <https://docs.pytest.org/en/stable/how-to/skipping.html>`__
   for additional test control

.. code-block:: python
    :linenos:

    import pytest
    import waft

    from waft import fixture


    @waft.mark.defect(
        "CLIENT-11493",
        "warp_tunnel_only service mode unable to connect",
        "Tunnel only mode does not exclude all local DNS servers",
    )
    def test_example(system: fixture.system):
        """This test definition serves as an example of how to
        define a test that is affected by JIRA reported defects.

        1. The test will log an error and warning for CLIENT-11493,
           tag and link the defect in the Allure report, unconditionally.

        2. The test will log an error for CLIENT-11494
           before skipping the test, when run with a Windows test system.
        """
        if system.node.platform_is_windows:
            waft.mark.defect(
                "CLIENT-11494",
                "posture_only service mode unable to connect on Windows",
            )
            pytest.skip(
                "Windows login session required to install certificate."
            )