Getting started guide

This part of document will briefly familiarize the reader with the necessary steps to prepare the all the dependencies required to run PatrIoT framework as well as prepare the development environment to ensure efficient development of testing program.

Prerequisities

PatrIoT framework is using open-source technologies that allows test developer to easily prepare and conduct testing of IoT applications. Such technologies have the advantage of being ready to deploy to most of the open-source friendly operating systems with prebuilt artifacts, which are working out of the box. In order to run the tests with PatrIoT Framework you need following list of software ready on your development machine:

  • Machine with Linux (recommended Fedora)

  • Java 8 or 11 installed.

  • Java JDK installed

  • docker

  • Maven

Installation on various Linux distributions

Following part describes how to install dependencies on various Linux distributions.

Fedora 30

To install java please write following command as root:

# dnf install java-1.8.0-openjdk.x86_64 java-1.8.0-openjdk-devel.x86_64 maven

To install docker we’ll need to first enable it’s repository:

# dnf -y install dnf-plugins-core
# dnf config-manager \
   --add-repo https://download.docker.com/linux/fedora/docker-ce.repository
# dnf makecache

Then we can install docker and enable its service:

# dnf install docker-ce docker-ce-cli containerd.io
# systemctl enable --now docker.service
Ubuntu 20.04

As in example with fedora we’ll need to use root access to the system, since we’re going to perform administrative tasks, in order to install necessary packages run following commands in terminal:

# apt install openjdk-8-jdk maven

To install docker we just need to install docker.io package, enable and start the service, this can be achieved by following commands:

# apt install docker.io
# sytemctl enable --now docker.service
Resolving issues with user access to the docker service

On new installations of docker it might happen that basic user doesn’t have rights to run docker containers. This is due to the neccessary security elevation to access the docker daemon. For this problem there are two principal solutions:

  • Execute tests as user root - highly discouraged since it might compromise the whole system and it is also highly impractical.

  • Allow specific user to use docker daemon directly - solution which is more common as well as is more safe in case of test or development failure.

To allow specific user to use docker daemon the process generally consists of two steps. First creating unix group on the development machine which has allows access to the docker.sock and second: to add specific user to selected group. For specific actions - if necessary - please consult official docker documentation, which describes this situation in more detail and contains steps necessary to enable common user to access the docker daemon.

Creating pom.xml

Patriot framework is dependent on and integrated into Junit 5. Hence to create the testing project the first step will be to create Maven project.

Setting up the project

To setup project we’ll start with creating the file structure necessary for the testing. Let’s assume our tetsing project will be named my-simple-test. Then we can create proceed with following commands:

$ mkdir my-simple-test
$ cd my-simple-test
$ mkdir my-simple-test/{src,test}
$ touch pom.xml

Fill in pom.xml

The next step is to create initial structure for maven in order to execute tests. Following snippet shows initial configuration of the project itself

Minimal pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>

   <groupId>my-group</groupId>
   <artifactId>my-simple-test</artifactId>
   <version>1.0-SNAPSHOT</version>

   <properties>
      <junit.jupiter.version>5.4.0</junit.jupiter.version>
      <patriot.framework.version>3.0.0</patriot.framework.version>
   </properties>

</project>

To enable usage of PatrIoT framework you need to add those packages as dependency into the dependency section:

PatrIoT as a dependency
<dependencies>
      <dependency>
         <groupId>io.patriot-framework</groupId>
         <artifactId>patriot-api</artifactId>
         <version>${patriot.framework.version}</version>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>io.patriot-framework</groupId>
         <artifactId>docker-network-simulator</artifactId>
         <version>${patriot.framework.version}</version>
      </dependency>
</dependencies>

Since PatrIoT framework depends on JUnit as Test execution engine, you’ll need to add JUnit as well:

Junit dependency
   <dependencies>
      <dependency>
         <groupId>org.junit.jupiter</groupId>
         <artifactId>junit-jupiter-api</artifactId>
         <version>5.4.0</version>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>org.junit.jupiter</groupId>
         <artifactId>junit-jupiter-engine</artifactId>
         <version>5.4.0</version>
         <scope>test</scope>
      </dependency>
    </dependencies>

The pom.xml that could be used for bootsraping your configuration can be seen in following sinppet:

Full pom.xml illustrating configuration
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>

   <groupId>com.example</groupId>
   <artifactId>smarthouse-tests</artifactId>
   <version>1.0-SNAPSHOT</version>

   <properties>
      <junit.jupiter.version>5.4.0</junit.jupiter.version>
      <patriot.framework.version>2.0.0</patriot.framework.version>
   </properties>

   <dependencies>
      <dependency>
         <groupId>org.slf4j</groupId>
         <artifactId>slf4j-simple</artifactId>
         <version>1.7.5</version>
      </dependency>
      <dependency>
         <groupId>io.patriot-framework</groupId>
         <artifactId>patriot-api</artifactId>
         <version>${patriot.framework.version}</version>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>io.patriot-framework</groupId>
         <artifactId>docker-network-simulator</artifactId>
         <version>${patriot.framework.version}</version>
      </dependency>
      <dependency>
         <groupId>org.junit.jupiter</groupId>
         <artifactId>junit-jupiter-api</artifactId>
         <version>5.4.0</version>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>org.junit.jupiter</groupId>
         <artifactId>junit-jupiter-engine</artifactId>
         <version>5.4.0</version>
         <scope>test</scope>
      </dependency>

   </dependencies>

   <build>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.7.0</version>
            <configuration>
               <source>8</source>
               <target>8</target>
            </configuration>
         </plugin>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.0.0-M1</version>
            <configuration>
               <systemPropertyVariables>
                  <junit.jupiter.extensions.autodetection.enabled>true</junit.jupiter.extensions.autodetection.enabled>
               </systemPropertyVariables>
            </configuration>
         </plugin>
      </plugins>
   </build>

</project>