watchOS With SwiftUI by Tutorials!

Build awesome apps for Apple Watch with SwiftUI,
the declarative and modern way.

Home Server-Side Swift Tutorials

Testing in Vapor 4

Use a pre-built Vapor application to learn both how to test your server-side Swift Vapor apps on macOS and also best practices to simplify your test code.

4.6/5 5 Ratings

Version

  • Swift 5, macOS 11, Xcode 12

Testing is an important part of the software development process. Writing unit tests and automating them as much as possible allows you to develop and evolve your applications quickly.

In this server-side Swift tutorial, you’ll learn how to write tests for your Vapor applications. You’ll learn why testing is important, how it works with Swift Package Manager (SwiftPM), and how to write tests for your application.

More information on testing and using the XCTVapor module in Vapor 4 may be found in the Vapor documentation.

Why Should You Write Tests?

Software testing is as old as software development itself. Modern server applications are deployed many times a day, so it’s important that you’re sure everything works as expected. Writing tests for your application gives you confidence the code is sound.

Testing also gives you confidence when you refactor your code. Testing every part of your application manually is slow and laborious, even when your application is small! To develop new features quickly, you want to ensure the existing features don’t break. Having an expansive set of tests allows you to verify everything still works as you change your code.

Testing can also help you design your code. Test-driven development is a popular development process in which you write tests before writing code. This helps ensure you have full test coverage of your code. Test-driven development also helps you design your code and APIs.

Note: This tutorial assumes you have some experience with using Vapor to build web apps. See Getting Started with Server-side Swift with Vapor 4 if you’re new to Vapor. This tutorial also assumes you have some experience working with the command line, Fluent, and Docker.

For information on using Fluent in Vapor, see Using Fluent and Persisting Models in Vapor.

If you’re new to Docker, check out Docker on macOS: Getting Started.

Getting Started

Download the starter project for this tutorial using the Download Materials button at the top or bottom of this tutorial.

The starter project contains a pre-built Vapor app named TIL (Today I Learned) that hosts user-supplied acronyms.

On iOS, Xcode links tests to a specific test target. Xcode configures a scheme to use that target and you run your tests from within Xcode. The Objective-C runtime scans your XCTestCases and picks out the methods whose names begin with test. On Linux, and with SwiftPM, there’s no Objective-C runtime. There’s also no Xcode project to remember schemes and which tests belong where.

In Xcode, open Package.swift. There’s a test target defined in the targets array:

.testTarget(name: "AppTests", dependencies: [
  .target(name: "App"),
  .product(name: "XCTVapor", package: "vapor"),
])

This defines a testTarget type with a dependency on App and Vapor’s XCTVapor. Tests must live in the Tests/<target directory> directory. In this case, that’s Tests/AppTests.

Xcode creates the TILApp scheme and adds AppTests as a test target to that scheme. You can run these tests as normal with Command-U, or Product ▸ Test:

TIL App Scheme

Testing Users

Writing your First Test

Create a new file in Tests/AppTests called UserTests.swift. This file will contain all the user-related tests. Open the new file and insert the following:

@testable import App
import XCTVapor

final class UserTests: XCTestCase {
}

This creates the XCTestCase you’ll use to test your users and imports the necessary modules to make everything work.

Next, add the following inside UserTests to test getting the users from the API:

func testUsersCanBeRetrievedFromAPI() throws {
  // 1
  let expectedName = "Alice"
  let expectedUsername = "alice"

  // 2
  let app = Application(.testing)
  // 3
  defer { app.shutdown() }
  // 4
  try configure(app)

  // 5
  let user = User(
    name: expectedName,
    username: expectedUsername)
  try user.save(on: app.db).wait()
  try User(name: "Luke", username: "lukes")
    .save(on: app.db)
    .wait()

  // 6
  try app.test(.GET, "/api/users", afterResponse: { response in
    // 7
    XCTAssertEqual(response.status, .ok)

    // 8
    let users = try response.content.decode([User].self)
    
    // 9
    XCTAssertEqual(users.count, 2)
    XCTAssertEqual(users[0].name, expectedName)
    XCTAssertEqual(users[0].username, expectedUsername)
    XCTAssertEqual(users[0].id, user.id)
  })
}

There’s a lot going on in this test; here’s the breakdown:

  1. Define some expected values for the test: a user’s name and username.
  2. Create an Application, similar to main.swift. This creates an entire Application object but doesn’t start running the application. Note, you’re using the .testing environment here.
  3. Shutdown the application at the end of the test. This ensures that you close database connections correctly and clean up event loops.
  4. Configure your application for testing. This helps ensure you configure your real application correctly as your test calls the same configure(_:).
  5. Create a couple of users and save them in the database.
  6. Create a Responder type; this is what responds to your requests.
  7. Use XCTVapor — Vapor’s testing module — to send a GET request to /api/users. With XCTVapor you specify a path and HTTP method. XCTVapor also allows you to provide closures to run before you send the request and after you receive the response.
  8. Ensure the response received contains the expected status code.
  9. Decode the response data into an array of Users.
  10. Ensure there are the correct number of users in the response and the users match those created at the start of the test.

Support Testing in Your Configuration

Next, you must update your app’s configuration to support testing. Open configure.swift and before app.databases.use add the following:

let databaseName: String
let databasePort: Int
// 1
if (app.environment == .testing) {
  databaseName = "vapor-test"
  databasePort = 5433
} else {
  databaseName = "vapor_database"
  databasePort = 5432
}

This sets properties for the database name and port depending on the environment. You’ll use different names and ports for testing and running the application. Next, replace the call to app.databases.use with the following:

app.databases.use(.postgres(
  hostname: Environment.get("DATABASE_HOST")
    ?? "localhost",
  port: databasePort,
  username: Environment.get("DATABASE_USERNAME")
    ?? "vapor_username",
  password: Environment.get("DATABASE_PASSWORD")
    ?? "vapor_password",
  database: Environment.get("DATABASE_NAME")
    ?? databaseName
), as: .psql)

This sets the database port and name from the properties set above if you don’t provide environment variables. These changes allow you to run your tests on a database other than your production database. This ensures you start each test in a known state and don’t destroy live data.

The VaporTIL app was developed using Docker to host the app database. Setting up another database on the same machine for testing is straightforward. In Terminal, type the following:

docker run --name postgres-test -e POSTGRES_DB=vapor-test \
  -e POSTGRES_USER=vapor_username -e POSTGRES_PASSWORD=vapor_password \
  -p 5433:5432 -d postgres

This changes the container name and database name. The Docker container is also mapped to host port 5433 to avoid conflicting with the existing database.

Run the tests and they should pass. However, if you run the tests again, they’ll fail. The first test run added two users to the database and the second test run now has four users since the database wasn’t reset.

preformed 2 test

User test passed first time only.

Open UserTests.swift and add the following after try configure(app):

try app.autoRevert().wait()
try app.autoMigrate().wait()

This adds commands to revert any migrations in the database and then run the migrations again. This provides you with a clean database for every test.

Build and run the tests again and this time they’ll pass!

Executed two successful test

Now, test will pass each time they are run because you have added commands to revert any migrations.

Test Extensions

The first test contains a lot of code that all tests need. You can extract the common parts to make the tests easier to read and to simplify future tests. In Tests/AppTests create a new file for one of these extensions, called Application+Testable.swift. Open the new file and add the following:

import XCTVapor
import App

extension Application {
  static func testable() throws -> Application {
    let app = Application(.testing)
    try configure(app)
    
    try app.autoRevert().wait()
    try app.autoMigrate().wait()

    return app
  }
}

This function allows you to create a testable Application object, configure it and set up the database. Next, create a new file in Tests/AppTests called Models+Testable.swift. Open the new file and create an extension to create a User:

@testable import App
import Fluent

extension User {
  static func create(
    name: String = "Luke",
    username: String = "lukes",
    on database: Database
  ) throws -> User {
    let user = User(name: name, username: username)
    try user.save(on: database).wait()
    return user
  }
}

This function saves a user, created with the supplied details, in the database. It has default values so you don’t have to provide any if you don’t care about them.

With all this created, you can now rewrite your user test. Open UserTests.swift and delete testUsersCanBeRetrievedFromAPI().

In UserTests create the common properties for all the tests:

let usersName = "Alice"
let usersUsername = "alicea"
let usersURI = "/api/users/"
var app: Application!

Next, implement setUpWithError() to run the code that must execute before each test:

override func setUpWithError() throws {
  app = try Application.testable()
}

This creates an Application for the test, which also resets the database.

Next, implement tearDownWithError() to shut the application down:

override func tearDownWithError() throws {
  app.shutdown()
}

Finally, rewrite testUsersCanBeRetrievedFromAPI() to use all the new helper methods:

func testUsersCanBeRetrievedFromAPI() throws {
  let user = try User.create(
    name: usersName, 
    username: usersUsername, 
    on: app.db)
  _ = try User.create(on: app.db)

  try app.test(.GET, usersURI, afterResponse: { response in
    XCTAssertEqual(response.status, .ok)
    let users = try response.content.decode([User].self)
    
    XCTAssertEqual(users.count, 2)
    XCTAssertEqual(users[0].name, usersName)
    XCTAssertEqual(users[0].username, usersUsername)
    XCTAssertEqual(users[0].id, user.id)
  })
}

This test does exactly the same as before but is far more readable. It also makes the next tests much easier to write. Run the tests again to ensure they still work.

Test executed successfully

Test executed with extensions

Testing the User API

In UserTests.swift, use the test helper methods to test saving a user via the API by adding the following test method:

func testUserCanBeSavedWithAPI() throws {
  // 1
  let user = User(name: usersName, username: usersUsername)
  
  // 2
  try app.test(.POST, usersURI, beforeRequest: { req in
    // 3
    try req.content.encode(user)
  }, afterResponse: { response in
    // 4
    let receivedUser = try response.content.decode(User.self)
    // 5
    XCTAssertEqual(receivedUser.name, usersName)
    XCTAssertEqual(receivedUser.username, usersUsername)
    XCTAssertNotNil(receivedUser.id)
    
    // 6
    try app.test(.GET, usersURI, 
      afterResponse: { secondResponse in
        // 7
        let users = 
          try secondResponse.content.decode([User].self)
        XCTAssertEqual(users.count, 1)
        XCTAssertEqual(users[0].name, usersName)
        XCTAssertEqual(users[0].username, usersUsername)
        XCTAssertEqual(users[0].id, receivedUser.id)
      })
  })
}

Here’s what the test does:

  1. Create a User object with known values.
  2. Use test(_:_:beforeRequest:afterResponse:) to send a POST request to the API
  3. Encode the request with the created user before you send the request.
  4. Decode the response body into a `User` object.
  5. Assert the response from the API matches the expected values.
  6. Make another request to get all the users from the API.
  7. Ensure the response only contains the user you created in the first request.

Run the tests to ensure that the new test works!

API test successful

Test saving a user via the API.

Next, add the following test to retrieve a single user from the API:

func testGettingASingleUserFromTheAPI() throws {
  // 1
  let user = try User.create(
    name: usersName, 
    username: usersUsername, 
    on: app.db)
  
  // 2
  try app.test(.GET, "\(usersURI)\(user.id!)", 
    afterResponse: { response in
      let receivedUser = try response.content.decode(User.self)
      // 3
      XCTAssertEqual(receivedUser.name, usersName)
      XCTAssertEqual(receivedUser.username, usersUsername)
      XCTAssertEqual(receivedUser.id, user.id)
    })
}

Here’s what the test does:

  1. Save a user in the database with known values.
  2. Get the user at /api/users/<USER ID>.
  3. Assert the values are the same as provided when creating the user.

The final part of the user’s API to test retrieves a user’s acronyms. Open Models+Testable.swift and, at the end of the file, create a new extension to create acronyms:

extension Acronym {
  static func create(
    short: String = "TIL",
    long: String = "Today I Learned",
    user: User? = nil,
    on database: Database
  ) throws -> Acronym {
    var acronymsUser = user

    if acronymsUser == nil {
      acronymsUser = try User.create(on: database)
    }

    let acronym = Acronym(
      short: short,
      long: long,
      userID: acronymsUser!.id!)
    try acronym.save(on: database).wait()
    return acronym
  }
}

This creates an acronym and saves it in the database with the provided values. If you don’t provide any values, it uses defaults. If you don’t provide a user for the acronym, it creates a user to use first.

Open UserTests.swift and create a method to test getting a user’s acronyms:

func testGettingAUsersAcronymsFromTheAPI() throws {
  // 1
  let user = try User.create(on: app.db)
  // 2
  let acronymShort = "OMG"
  let acronymLong = "Oh My God"
  
  // 3
  let acronym1 = try Acronym.create(
    short: acronymShort, 
    long: acronymLong, 
    user: user, 
    on: app.db)
  _ = try Acronym.create(
    short: "LOL", 
    long: "Laugh Out Loud", 
    user: user, 
    on: app.db)

  // 4
  try app.test(.GET, "\(usersURI)\(user.id!)/acronyms", 
    afterResponse: { response in
      let acronyms = try response.content.decode([Acronym].self)
      // 5
      XCTAssertEqual(acronyms.count, 2)
      XCTAssertEqual(acronyms[0].id, acronym1.id)
      XCTAssertEqual(acronyms[0].short, acronymShort)
      XCTAssertEqual(acronyms[0].long, acronymLong)
    })
}

Here’s what the test does:

  1. Create a user for the acronyms.
  2. Define some expected values for an acronym.
  3. Create two acronyms in the database using the created user. Use the expected values for the first acronym.
  4. Get the user’s acronyms from the API by sending a request to /api/users/<USER ID>/acronyms.
  5. Assert the response returns the correct number of acronyms and the first one matches the expected values.

Run the tests to ensure that the changes work!

User's acronyms test successful.

Testing for a user’s acronyms.

Testing Acronyms and Categories

Open Models+Testable.swift and, at the bottom of the file, add a new extension to simplify creating acronym categories:

extension App.Category {
  static func create(
    name: String = "Random",
    on database: Database
  ) throws -> App.Category {
    let category = Category(name: name)
    try category.save(on: database).wait()
    return category
  }
}

Like the other model helper functions, create(name:on:) takes the name as a parameter and creates a category in the database. The tests for the acronyms API and categories API are part of the starter project for this tutorial. Open CategoryTests.swift and uncomment all the code. The tests follow the same pattern as the user tests.

Open AcronymTests.swift and uncomment all the code. These tests also follow a similar pattern to before but there are some extra tests for the extra routes in the acronyms API. These include updating an acronym, deleting an acronym and the different Fluent query routes.

Run all the tests to make sure they all work. You should have a sea of green tests with every route tested!

All Tests Passing

Where to Go From Here?

You can download the completed project for this tutorial using the Download Materials button at the top or bottom of this tutorial.

In this tutorial, you learned how to test your Vapor applications to ensure they work correctly. Server-side Swift apps are typically deployed to Linux, and writing tests for your application means you can run these tests on Linux. This gives you confidence the application will work when you deploy it. Having a good test suite allows you to evolve and adapt your applications quickly. To learn about testing Vapor applications on Linux, see Server-Side Swift: Testing on Linux.

Vapor’s architecture has a heavy reliance on protocols. This, combined with Vapor’s dependency injection Service framework, makes testing simple and scalable. For large applications, you may even want to introduce a data abstraction layer so you aren’t testing with a real database.

This means you don’t have to connect to a database to test your main logic and will speed up the tests.

It’s important you run your tests regularly. Using a continuous integration (CI) system such as Jenkins or Bitbucket Pipelines allows you to test every commit. You must also keep your tests up to date.

Questions or comments on this tutorial? Leave them in the comments below!

More like this

Contributors

Comments