# Contents

- [Contents](#contents)
- [Test Environment Architecture](#test-environment-architecture)
- [Test Environment Configuration](#test-environment-configuration)
  - [Config System Under Test](#config-system-under-test)
  - [Setup Driver Computer to Run Test Suite](#setup-driver-computer-to-run-test-suite)
    - [Setup Driver Computer to run test suite with PTM](#setup-driver-computer-to-run-test-suite-with-ptm)
    - [Setup a Linux Driver Computer to run test suite](#setup-a-linux-driver-computer-to-run-test-suite)
      - [Run test suite with released binaries](#run-test-suite-with-released-binaries)
      - [Build and run test suite from scratch](#build-and-run-test-suite-from-scratch)
      - [Run test suite in Docker image on Linux computer](#run-test-suite-in-docker-image-on-linux-computer)
    - [Setup a macOS or Windows Driver Computer with Docker image to run test suite](#setup-a-macos-or-windows-driver-computer-with-docker-image-to-run-test-suite)

# Test Environment Architecture

The Test Environment consists of a Driver computer (client) and SUT computers (server) in a workgroup environment.

# Test Environment Configuration

## Config System Under Test

Take a Windows SUT (computer name eg. RDPSrv-SUT01) as an example for the configuration description.

1. Disable Firewall on the RDPSrv-SUT01
2. Start Remote Desktop Services

## Setup Driver Computer to Run Test Suite

Before config the Driver Computer and run test suite, please config and check the Driver Computer as below:

1. [Check the minimum requirement of a Driver computer](https://github.com/microsoft/WindowsProtocolTestSuites/blob/main/TestSuites/RDP/Server/Docs/RDP_ServerUserGuide.md#_Toc396908226)

2. [Verify Network Computer Connectivity](https://github.com/microsoft/WindowsProtocolTestSuites/blob/main/TestSuites/RDP/Server/Docs/RDP_ServerUserGuide.md#_Toc396908230)

### Setup Driver Computer to run test suite with PTM

On Driver Computer, install the dependent software following: [Windows Protocol TestSuites Prerequisite](https://github.com/microsoft/WindowsProtocolTestSuites#prerequisites)

Then install the latest released [RDP Server test suite](https://github.com/microsoft/WindowsProtocolTestSuites/releases) by downloading and extracting the zip file to local drive.

You can use the Protocol Test Manager to run test suite. More details about how to run test suite with PTM, please check the [RDP Server User Guide](https://github.com/microsoft/WindowsProtocolTestSuites/blob/ptm@4.21.9.0/TestSuites/RDP/Client/docs/RDP_ClientUserGuide.md)

### Setup a Linux Driver Computer to run test suite

There are 3 ways to setup a Linux Driver Computer to run test suite:

1. [Run test suite with released binaries](####Run-test-suite-with-released-binaries)
2. [Build and run test suite from scratch](####Build-and-run-test-suite-from-scratch)
3. [Run test suite in Docker image](####Run-test-suite-in-Docker-image-on-Linux-computer)

Before run test suite, .NET SDK is required to be configured properly on the Linux Driver Computer.

- **Install .NET SDK**

    ```bash
    wget https://packages.microsoft.com/config/ubuntu/20.10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
    sudo dpkg -i packages-microsoft-prod.deb

    sudo apt-get update
    sudo apt-get install -y apt-transport-https
    sudo apt-get update 
    sudo apt-get install -y dotnet-sdk-6.0
    ```

#### Run test suite with released binaries

1. Download test suite source released binaries from GitHub to /home/iolab

    ```bash
    wget https://github.com/microsoft/WindowsProtocolTestSuites/releases/download/4.21.1.0/RDP-TestSuite-ServerEP.tar.gz -L -O RDPServer.tar.gz
    ```

2. Unzip test suite binaries

    ```bash
    mkdir RDPServer
    tar -C /home/iolab/RDPServer -zxvf /home/iolab/RDPServer.tar.gz
    ```

3. Update the ptfconfig files

    Located at the local config path at /home/iolab/RDPServer/RDP_ServerTestSuite.deployment.ptfconfig. Update the RDP.ServerName with the SUT IP (192.168.142.21 for example) . Update RDP.ClientName with the current Linux Driver Computer (192.168.142.11 for example).

    ```xml
    <Property name="RDP.ServerName" value="192.168.142.21" />
    <Property name="RDP.ClientName" value="192.168.142.11" />
    ```

4. Run test case under /home/iolab/RDPServer/Bin with the commands below for different binaries.

    ```bash
    dotnet test RDP_ServerTestSuite.dll --logger:"trx;LogFileName=RDPServerResult.trx"
    ```

#### Build and run test suite from scratch

You can also clone the source code and build by yourself. Here are the steps to follow:

1. Clone source code from [GitHub website](https://github.com/microsoft/WindowsProtocolTestSuites) to local driver, eg. /home/iolab/

    ```bash
    sudo apt install git
    git clone https://github.com/microsoft/WindowsProtocolTestSuites
    ```

2. Update the ptfconfig files

    Located at the local config path at /home/iolab/RDPServer/RDP_ServerTestSuite.deployment.ptfconfig. Update the RDP.ServerName with the SUT IP (192.168.142.21 for example) . Update RDP.ClientName with the current Linux Driver Computer (192.168.142.11 for example).

    ```xml
    <Property name="RDP.ServerName" value="192.168.142.21" />
    <Property name="RDP.ClientName" value="192.168.142.11" />
    ```

3. Build RDPServer test suite:

    During the build, PTF will be downloaded from NuGet website side-by-side.

    Build script:

    ```powershell
    cd /home/iolab/WindowsProtocolTestSuites/TestSuites/RDP/Server/src
    build.ps1 Release published
    ```

    or

    ```bash
    cd /home/iolab/WindowsProtocolTestSuites/TestSuites/RDP/Server/src
    chmod +x ./build.sh
    ./build.sh Release published
    ```

    *Note*
    *the first parameter for build script is the build environment(like Release, Debug) and the second parameter is the output folder*

    After the build succeeds, the common folder structure should be generated in the folder `/home/iolab/WindowsProtocolTestSuites/TestSuites/RDP/Server/src/published`

    - Bin: all the built binaries including ProtoSDK, adapters and test suites.
    - Batch: batch files (.ps1, .sh) which can be used to launch tests.
    - Scripts: scripts which can be used to configure test environment.

4. Run test suite with Batch

    In the `Batch` folder under root path of the test suite, there are several scripts you can use to launch tests.

    - Run all test cases

        Execute `RunAllTestCases.ps1` in PowerShell, or `RunAllTestCases.sh` in shell directly.

    - Run test cases by filters

        Execute `./RunTestCasesByFilter.ps1 -Filter [your filter expression]` in PowerShell, or `./RunTestCasesByFilter.sh [your filter expression]` in shell directly.

        For example, you can run below command if you want to run test cases with test category `BVT` and `RDPBCGR`:

        ```bash
        ./RunTestCasesByFilter.sh "TestCategory=BVT&TestCategory=RDPBCGR"
        ```

        For more information about how to construct the filter expression, you can refer to Filter option details.

    - Dry run

        If you want to list the test cases before running them actually, you could add `-DryRun` switch to `.ps1` scripts or pass a non-empty string as the last argument to `.sh` scripts.

        For example, you can run below command if you want to list test cases with test category `BVT` and `RDPBCGR`:

        ```bash
        RunTestCasesByFilter.sh "TestCategory=BVT&TestCategory=RDPBCGR" "list"
        ```

#### Run test suite in Docker image on Linux computer

Refer [How-to-Run-Test-Suites-with-Docker](https://github.com/microsoft/WindowsProtocolTestSuites/wiki/How-to-Run-Test-Suites-with-Docker) for more details

1. Install Docker

    ```bash
    sudo apt install docker.io
    ```

2. Pull Docker image from Docker Hub

    ```bash
    sudo docker pull mcr.microsoft.com/windowsprotocoltestsuites:rdpserver
    ```

3. Download ptfconfig file from GitHub
    Download the ptfconfig file from the GitHub link:

    ```bash
    https://github.com/microsoft/WindowsProtocolTestSuites/releases/download/4.21.1.0/rdpserver-docker-ptfconfig.tar.gz
    ```

    Unzip it to the local path of Linux host machine (/data/rdpserver for example) before ahead.

    ```bash
    wget https://github.com/microsoft/WindowsProtocolTestSuites/releases/download/4.21.1.0/rdpserver-docker-ptfconfig.tar.gz -L -O RDPServerPtfconfig.tar.gz
    
    mkdir RDPServerPtfconfig
    tar -C /home/iolab/RDPServerPtfconfig -zxvf /home/iolab/RDPServerPtfconfig.tar.gz
    ```

4. Update the ptfconfig files

    Located at /home/iolab/RDPServer/RDP_ServerTestSuite.deployment.ptfconfig. Update the RDP.ServerName with the SUT IP (192.168.142.21 for example) . Update RDP.ClientName as the docker container VM name "RDPClient".

    ```xml
    <Property name="RDP.ServerName" value="192.168.142.21" />
    <Property name="RDP.ClientName" value="RDPClient" />
    ```

5. Run the Windows protocol test suites image for RDPServer with parameters:

    ```bash
    docker run \
      --hostname RDPServer \
      --network host \
      -v /path/of/ptfconfig:/data/rdpserver \
      [optional]$filter \
      [optional]$dryRun \
      -i mcr.microsoft.com/windowsprotocoltestsuites:rdpserver \
    ```

    - --hostname: Required. The host name of the running container, for example: RDPClient
    - --network: Required. The network the running container will use, using host as default. While using host, please make sure that the
        connection between the host which the container is running and the server is valid.
    - -v: Required. The /path/of/ptfconfig should include all the ptfconfig files with pre-configured, and mount this path to the fixed path
        /data/rdpserver in the container
    - -i: Required. Keep STDIN open even if not attached.
    - $filter: Optional. The expression used to filter test cases. For example, "TestCategory=BVT&TestCategory=RDPBCGR" will filter out test
        cases with test category BVT and RDPBCGR.
    - $dryRun: Optional. If set as "y", just list all the test cases match the filter string instead of running them. If it's null or empty,
        the filtered test cases will be executed directly

    For example, the command below will run the test cases with category RDPBCGR.

    ```bash
    sudo docker run \
      --hostname RDPClient \
      --network host \
      -v /home/iolab/RDPServerPtfconfig/rdpserver-docker-ptfconfig:/data/rdpserver \
      -e Filter="'TestCategory=RDPBCGR'" \
      -e DryRun="" \
      -i mcr.microsoft.com/windowsprotocoltestsuites:rdpserver
    ```

### Setup a macOS or Windows Driver Computer with Docker image to run test suite

1. Install docker desktop version on your macOS or Windows Driver Computer, for Windows platform you need switch to Linux containers
2. Pull image

    ```bash
    docker pull mcr.microsoft.com/windowsprotocoltestsuites:rdpserver
    ```

3. Update the ptfconfig files

    Located at /home/iolab/RDPServer/RDP_ServerTestSuite.deployment.ptfconfig. Update the RDP.ServerName with the SUT IP (192.168.142.21 for example) . Update RDP.ClientName as the docker container VM name "RDPClient".

    ```xml
    <Property name="RDP.ServerName" value="192.168.142.21" />
    <Property name="RDP.ClientName" value="RDPClient" />
    ```

4. Start the container by running the following command.

    ```bash
    docker run \
      --hostname RDPClient \
      -p 3389:3389 \
      -v C:\RDPServer\RDPServerPtfconfig\rdpserver-docker-ptfconfig:/data/rdpserver \
      -e Filter="'TestCategory=RDPBCGR'" \
      -e DryRun="" \
      -i mcr.microsoft.com/windowsprotocoltestsuites:rdpserver
    ```

    You will see output flows out to the host console, and the test result of the test cases filtered by the filter TestCategory=BVT&TestCategory=RDPBCGR will be found in your local config path when the execution is complete.

    Use below command then you can execute shell on docker container VM

    ```bash
    docker exec -it {image id} bash
    ```