Teacup - Testing Framework for Communication Protocols and Web Services

Teacup makes it possible to test communication protocols. The core project is not dependent on any engine, protocol or reporter, making the framework flexible and powerful.

The idea is that it should be easy to add/change/remove engines, protocols and reporters without changing any of the API's.

1. Create your test project
2. Choose engine(s)
3. Choose protocol(s)
4. Choose reporter(s)

• Core
• Engine
  • JUnit
• Protocol
  • FTP/FTPS
  • HTTP/HTTPS
  • Telnet
• Report
  • File
  • MySQL
• Visualization
  • Back-end
  • Front-end
• Service
  • Report MySQL
  • Visualization MySQL
• Example

Core

What

The core project has three main responsibilities and does not rely on any special test engine or protocol:

Assertions

A big library with all the base assertions such as arrays, lists and primitives.

Interfaces

Interfaces such as Node, Result and Reporter.

Setup

Support for fixtures and other setup-related functionality.

Why

The framework does not rely on any specific test engine or protocol.
It is built to be able to be easy to use, extend and maintain.

How

This is possible due to highly use of interfaces and almost none of the implementation classes are exposed to the public.

The core project does not know anything about the test engine or protocols implemented, which makes the project very isolated.

Where

The project is found here:

Engine

What

Parent project for all engine implementations.
This project contains engine specific interfaces and base classes.

Why

It should be easy to add support for a new engines.

How

By extracting repeated code as much as possible.

Where

The project is found here:

JUnit

What

Custom JUnit 5 engine.
This engine interacts with the Teacup core project to get fixture data, such as the current fixture and added clients/servers.

Why

It can be time and resource consuming to use fixtures.
Therefore this engine will change the order of the tests before executing them so that the minimal fixture changes are required.

How

This is done by extending the Jupiter engine.

To use the Teacup engine, do as follows:

1. Create a file named org.junit.platform.engine.TestEngine in src/main/resources/META-INF/services
2. Add the content org.teacup.engine.junit.TeacupTestEngine
3. Add the engine to the build file, this is different depending on the build tool you are using.
   The best thing is to check this guide:
4. Write your tests as you would normally do with JUnit.

Where

The project is found here:

Protocol

What

Parent project for all protocol implementations.
This project contains protocol specific interfaces and base classes.

Why

It should be easy to add support for a new protocols.

How

By extracting repeated code as much as possible.

Where

The project is found here:

FTP/FTPS

What

FTP/FTPS support.

There is also support for an FTP server.

Why

This makes it possible to test FTP with the framework, both the client and the server.

How

Add this repository as a dependency.

The Client interface holds all the functionality that the FTP client can do.
The SecureClient interface holds all the functionality that the secure FTP client can do.
New clients can be created with the Factory class in the client package.

The SimpleServer interface holds all the functionality that the FTP server can do.
New servers can be created with the Factory class in the server package.

Where

The project is found here:

HTTP/HTTPS

What

HTTP version 1.1 and 2 support.

The framework supports asynchronously and synchronously requests.

There is also support for an HTTP/HTTPS server.

Why

This makes it possible to test HTTP with the framework, both the client and the server.

How

Add this repository as a dependency.

The Simple interface holds all the functionality that the HTTP client can do.
New clients can be created with the Factory class in the client package.

The Simple interface holds all the functionality that the HTTP server can do.
New servers can be created with the Factory class in the server package.

Where

The project is found here:

Telnet

What

Telnet support.

There is also support for an Telnet server.

Why

This makes it possible to test Telnet with the framework, both the client and the server.

How

Add this repository as a dependency.

The Client interface holds all the functionality that the Telnet client can do.
New clients can be created with the Factory class in the client package.

The Simple interface holds all the functionality that the Telnet server can do.
New servers can be created with the Factory class in the server package.

Where

The project is found here:

Report

File

What

This project makes it possible to save logs on disc rather than just publish on the screen.

Why

Save the logs on disc so that they are not deleted after each test execution, no matter what test engine you are using.

How

Follow the steps below:

1. Add this repository as a dependency
2. Create a file named teacup.properties in a folder named .teacup in your home folder
3. Add reporter=io.githb.henryssondaniel.teacup.report.file.DefaultReporter to the file

Where

The project is found here:

MySQL

What

This project makes it possible to save logs in a MySQL database rather than just publish on the screen.

Why

Save the logs to a MySQL database so that they are not deleted after each test execution, no matter what test engine you are using.

How

Follow the steps below:

1. Add this repository as a dependency
2. Create a file named teacup.properties in a folder named .teacup in your home folder
3. Add reporter=io.githb.henryssondaniel.teacup.report.mysql.DefaultReporter to the file
4. Also add
   1. reporter.mysql.password=[password]
   2. reporter.mysql.server.name=[name]
   3. reporter.mysql.user=[user]

Where

The project is found here:

Visualization

Back-end

What

Visualization web back-end. Choose between an implementation in either Java or Python.

Why

This project is needed so that the web front-end can interact with the server side and other Teacup projects.

How

Follow this guide to deploy to production.

Where

The Java project is found here:

The Python project is found here:

Front-end

What

Web front-end.

Why

To visualize the content from the reporters on a web page.

How

Deploy the application on your web server.

Where

The project is found here:

Service

Report MySQL

What

This project makes it possible to interact with a MySQL database to be used in the report projects.

Why

The report back-end does and should not know anything about where the data comes from. This makes it easy to switch from one database to another.

How

Follow the steps below:

• Deploy the war file on your server

Where

The project is found here:

Visualization MySQL

What

This project makes it possible to interact with a MySQL database to be used in the visualization projects.

Why

The visualization back-end does and should not know anything about where the data comes from. This makes it easy to switch from one database to another.

How

Follow the steps below:

• Deploy the war file on your server

Where

The project is found here:

Example

What

Examples using the JUnit test engine.

Why

It can be used as a reference to set up and write your first test case.

How

Add the dependencies

It has three dependencies:

• Core (io.github.henryssondaniel.teacup:core)
• JUnit test engine (io.github.henryssondaniel.teacup.engine:junit)
• HTTP protocol (io.github.henryssondaniel.teacup.protocol:http)

Add the test engine

• Create a file named io.github.henryssondaniel.junit.platform.engine.TestEngine in src/main/resources/META-INF/services
• Add the content io.github.henryssondaniel.teacup.engine.junit.TeacupTestEngine
• Add the engine to the build file, this is different depending on the build tool you are using.
• The best thing is to check: https://junit.org/junit5/docs/current/user-guide/#running-tests-build

Write your test (pseudocode)

Writing your test can be divided into three steps:

• response = client.send(request) // send the request
• node = responseBuilder.setStatusCode(statusCode).setVersion(version).build() // define the assertions
• node.verify(response) // verify

All assertions can be chained and all setters take an assertion rather than a value.
This means that statusCode and version represents assertions as well. The code could look similar to this:
statusCode = integerBuilder.isLessThan(300).isGreaterThanOrEqualTo(200).build()
version = versionBuilder.isSameAs(Version.2).build()

Where

The project is found here: