Mockingbird

This project is a demonstration of using the Swift Package Manager and writing Swift code to run on both Linux and macOS. It is built by developers at ustwo.

Usage

Installing & Running

Ensure you have the latest version of Xcode and Docker installed.

Run the setup script to install depedencies and perform an initial local build.

make setup

To setup a Docker container with the server, run the following command. Alternatively, if you have cloned this repository directly onto a Linux machine, you can install Swift by following Apple's instructions.

make build-docker

To start the server, from within the Docker container (or your Linux server) run the following command:

make run-docker

Testing & Linting

Test and linting scripts are all contained within the Makefile and can be run by make test and make lint respectively. Linting will check Ruby and Swift files and output them into a reports folder in the main directory.

Architecture

Organization

This repository is organised as specified by the Swift Package Manager. All source files for the mock server and client are included in the Sources folder with the corresponding tests in the Tests folder. A variety of useful scripts are contained in the Makefile. The project's resources are housed within the Resources folder.

Libraries and Executables

Each of the top level folders in Sources and Tests define a module. Each framework and test module is suffixed with Kit and Tests respectively. Following Swift Package Manager convention, test modules use the same name as their corresponding module and add the Tests suffix. Executables do not contain any suffix. Below is a brief description of each core module:

• MockServer: This is the server executable. It runs a basic HTTP server built with the MockServerKit.
• MockServerKit: This houses the business logic of the server. This is in a separate module from MockServer in order to make it testable. See SR-3033.
• ResourceKit: This contains helper files for managing resources as the Swift Package Manager does not currently have a good way to include them within a package. See SR-2866.
• SwaggerKit: This module parses a Swagger file and has convenience methods to build the HTTP server endpoints.
• TestKit: This library contains helper files for writting tests.

Dependencies

The Swift package is dependent on (as shown in Package.swift):

• HeliumLogger: This package provides additional logging functionality.
• Kitura: This framework provides the core of building an HTTP server.
• Swift-cenv: This library provides convenience methods for determining the environment on which the server is running.

Logging

By default, logging has been set at the verbose level for both the server and the tests. To adjust this, edit the line:

HeliumLogger.use(LoggerMessageType.verbose)

in the ServerController.swift for the server and LoggedTestCase.swift for the tests.

Open Swift Tickets & PR's

• SR-2866: The Swift Package Manager currently does not have a way to specify resources (such as assets, test files, etc.) to be included in the package. Mockingbird works around this by adding a COPY command in the Dockerfile and providing an absolute path to the resources in the code. To provide better support in Xcode, part of the xcodeproj_after_install.rb script adds the resources to a Copy Files Build Script Phase for the ResourceKit target. Thus ResourceKit has three ways for generating the appropriate file url for a given resource - absolute path using Linux (Docker) file layout when building on Linux, absolute path using the macOS file layout when using the Swift compiler on a Mac (i.e. swift build and swift test), or a resource bundle when using Xcode on a Mac.
• SR-3033: The Swift Package Manager currently cannot test an executable package (i.e. one with a main.swift file). Mockingbird works around this by placing as much code as possible within a library (MockServerKit) and only a minimal main.swift file in the executable (MockServer).
• SR-3583: The Swift Package Manager creates a .build folder when building. No distinction is made for the operating system when building. So if the .build folder is copied from a macOS build to a Linux server and run, it may or may not compile or test correctly. This GitHub PR seeks to either warn the user or place the build artifacts inside a top-level folder specifying the operating system. Mockingbird works around this by adding the .build folder to the .dockerignore file and doing a clean build on the Linux server. (For more history on this issue, see GitHub PR #807.)

License

Mockingbird is released under the MIT license. See LICENSE.md for details. Note that while Mock Mockingbird is licensed under the MIT license, not all of its dependencies are. Please check the depedencies listed in the Package.swift file and their respective licesnses.

Maintainers

• Aaron McTavish (@aamctustwo)

Contact

• open.source@ustwo.com