Skip to content

A fully typed Swift wrapper around TestRail's API

License

Notifications You must be signed in to change notification settings

jonny7/testrail-kit

Repository files navigation

TestRailKit

codecov testrail-ci license Maintainability

Overview

TestRailKit is an asynchronous pure Swift wrapper around the TestRail API, written on top of Apple's swift-nio and AsyncHTTPClient. Whereas other TestRail bindings generally provide some form of minimal client to send requests. This library provides the full type safe implementation of TestRail's API. Meaning that it will automatically encode and decode models to be sent and received and all the endpoints are already built in. These models were generally created by using our own unmodified TestRail instance and seeing what endpoints returned. But you can still make your own models easily.

Installing

Add the following entry in your Package.swift to start using TestRailKit:

.package(url: "https://github.com/jonny7/testrail-kit", from: "1.0.0-alpha.1")

Getting Started

import TestRailKit

let httpClient = HTTPClient(...)
let client = TestRailClient(httpClient: httpClient, eventLoop: eventLoop, username: "your_username", apiKey: "your-key", testRailUrl: "https://my-testrail-domain", port: nil) // `use port` if you're on a non-standard port

This gives you access to the TestRail client now. The library has extensive tests for all the endpoints, so you can always look there for example usage. At it's heart there are two main functions:

client.action(resource: ConfigurationRepresentable, body: TestRailPostable) -> TestRailModel // for posting models to TestRail
client.action(resource: ConfigurationRepresentable) -> TestRailModel // for retrieving models from TestRail

ConfigurationRepresentation: When calling either action method you will need to pass the resource argument, these all follow the same naming convention of TestRail resource, eg Case, Suite, Plan etc + "Resource". So the previously listed models all become CaseResource, SuiteResource, PlanResource. Each resource, then has various other enumerated options in order to provide an abstracted type-safe API, leaving the developer to pass simple typed arguments to manage TestRail.

For example:

let tests: EventLoopFuture<[Test]> = client.action(resource: TestResource.all(runId: 89, statusIds: [1]))).wait() // return all tests for run 89 with a status of 1

Note: Use of wait() was used here for simplicity. Never call this method on an eventLoop!

Conventions

TestRail uses Unix timestamps when working with dates. TestRailKit will encode or decode all Swift Date objects into UNIX timestamps automatically. TestRail also uses snake_case for property names, TestRailKit automatically encodes or decodes to camelCase as per Swift conventions

Customizing

If you wish to use a model that doesn't currently exist in the library because your own TestRail is mofidied you can simply make this model conform to TestRailModel if decoding it from TestRail or TestRailPostable if you wish to post this model to TestRail.

Partial Updates

TestRail supports partial updates, if you wish to use these, you will need to make this new object conform to TestRailPostable. You can see an example of this in the tests.

Vapor

For those who want to use this library with the most popular server side Swift framework Vapor, please see this repo.

Contributing

All help is welcomed, please open a PR