Custom Steps Reference
===================

The Cloud QA framework provides custom step definitions to simplify testing API endpoints. This section documents the available step definitions in the `features/steps/api/then*` and `features/steps/api/given*` files.

Given Steps
-----------

The `given.py` and `given_cloud.py` files contain step definitions for setting up the test environment and preparing API requests.

Request Preparation
~~~~~~~~~~~~~~~~

.. code-block:: gherkin

    # Steps NOT requiring data tables
    Given I am preparing a request for {api_type} api
    Given I am preparing a request
    Given I set "{key}" header to {method}
    Given I am setting the previous request as reference
    
    # Steps requiring data tables
    Given I set the request body as follow
      | name               | value              |
      | body_parameter_key | body_parameter_key |
    
    Given I set the request params as follow
      | name                  | value                   |
      | request_parameter_key | request_parameter_value |
These steps prepare API requests with the appropriate headers, body content, and parameters.

Request Execution
~~~~~~~~~~~~~~~~

.. code-block:: gherkin

    # Steps NOT requiring data tables
    Given I make a {request_verb} request to "{current_path}"
    Given I make a {request_verb} request to "{current_path}" with path parameter "{path_key}" as {method}
    Given I make the same request
    Given I make the same request setting "{key}" header to {method}
    Given I make the same request with path parameter "{path_key}" as {method}
    
    # Steps requiring data tables
    Given I make the same request setting the request body as follow
      | name               | value              |
      | body_parameter_key | body_parameter_key |

These steps execute different types of API requests with various parameters and path configurations.

Authentication and User Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: gherkin

    # Steps NOT requiring data tables
    Given I am logging as admin
    Given I am logging as user {user_index}
    Given I am getting the user {user_index}

These steps handle user authentication and retrieving user information.

Platform Management
~~~~~~~~~~~~~~~

.. code-block:: gherkin

    # Steps NOT requiring data tables
    Given I am registering a platform with "platform_name" as {platform_name_method}
    Given I am getting info of the platform with "platform_name_or_id" as {platform_name_or_id_method}
    Given I am deleting a platform with "platform_id" as {platform_id_method}
    Given I am fetching platform job with "platform_name" as {platform_name_method}
    Given I am assign user {user_index} to platform with "platform_id" as {platform_id_method}
    Given I am assign user {user_index} and its job token to platform with "platform_name" as {platform_name_method}
    
    # Steps requiring data tables
    Given I am registering a platform setting the payload as follow
      | name          | value                   |
      | platform_name | my platform name        |
      | description   | my platform description |

These steps manage platforms, including registration, deletion, and user assignment.

Job Management
~~~~~~~~~~~~

.. code-block:: gherkin

    # Steps NOT requiring data tables
    Given I am creating a job from user {user_index} on default platform
    Given I am creating a job from user {user_index} with "platform_name" as {platform_name_method}
    Given I am running the job with "job_id" as {job_id_method}
    Given I am getting the status of the job with "job_id" as {job_id_method} from user {user_index}
    Given I am getting the result of the job with "job_id" as {job_id_method} from user {user_index}
    Given I am getting the info of the job with "job_id" as {job_id_method}
    Given I am canceling the job with "job_id" as {job_id_method} from user {user_index}
    
    # Steps requiring data tables
    Given I am creating a job from user {user_index} setting the payload as follow
      | name       | value       |
      | job_name   | my job name |
      | parameters | ...         |
    
    Given I am making progress for the job with "job_id" as {job_id_method} setting the payload as follow
      | name       | value               |
      | progress   | progress percentage |
      | status     | job status          |
    
    Given I am finishing the job with "job_id" as {job_id_method} setting the payload as follow
      | name       | value      |
      | result     | my result  |
      | status     | job status |

These steps manage jobs, including creation, updating status, and cancellation.

Token Management
~~~~~~~~~~~~~

.. code-block:: gherkin

    # Steps NOT requiring data tables
    Given I am creating a new job token called {token_label} for user {user_index}
    Given I am assigning job token with "token_id" as {job_token_id_method} to platform with "platform_id" as {platform_id_method}

These steps handle token creation and assignment.

Variable Management
~~~~~~~~~~~~~~~~

.. code-block:: gherkin

    # Steps NOT requiring data tables
    Given I am saving a random uuid as {method}
    Given I am saving "{variable_key}" as {method}
    Given I am saving field "{variable_key}" from response as {method}
    Given The next section is testing {test_section_description}

These steps help manage variables and test context.

Test Control
~~~~~~~~~~~

.. code-block:: gherkin

    # Steps NOT requiring data tables
    Given I skip this scenario if LIGHT_VERSION is "{state}"

This step allows conditional execution of tests.

Then Steps
---------

The `then.py` and `then_cloud.py` files contain step definitions for verifying API responses and asserting expectations.

Response Validation
~~~~~~~~~~~~~~~~~

.. code-block:: gherkin

    # Steps NOT requiring data tables
    Then the response status code should equal {expected_http_status_code}
    Then the response should be empty
    Then the response should not be empty
    Then the response json matches defined schema
    Then the response should not be a pagination results
    
    # Steps requiring data tables
    Then the response should contain
      | name              | value             |
      | response_body_key | response_body_key |

These steps validate the API response status, content, and structure.

Examples
-------

Here's an example scenario using these custom steps:

.. code-block:: gherkin

    Scenario: Create a job and verify its status
      # Authentication without tables
      Given I am logging as admin
      
      # Platform creation with table
      Given I am preparing a request
      Given I am registering a platform setting the payload as follow
        | name          | value            |
        | platform_name | test-platform    |
        | description   | Test description |
      Then the response status code should equal 201
      
      # Job creation with table
      Given I am logging as user 1
      Given I am creating a job from user 1 setting the payload as follow
        | name       | value              |
        | job_name   | test-job           |
        | parameters | {"cores": 4}       |
        | platform   | test-platform      |
      Then the response status code should equal 201
      
      # Response validation with table
      Then the response should contain
        | field      | condition | value    |
        | id         | exists    | true     |
        | job_name   | equals    | test-job |
      
      # Get job info without tables
      Given I am getting the info of the job with "job_id" as "response.id"
      Then the response status code should equal 200
      Then the response should not be empty

Each step is implemented in Python code that handles the details of API interactions, allowing you to focus on writing clear and expressive tests.