Docs Menu

Test and Debug - Swift SDKicons/link.png

On this page

The easiest way to use and test Realm Database-backed applications is to use the default realm. To avoid overriding application data or leaking state between tests, set the default realm to a new file for each test.

// A base class which each of your Realm-using tests should inherit from rather
// than directly from XCTestCase
class TestCaseBase: XCTestCase {
override func setUp() {
// Use an in-memory Realm identified by the name of the current test.
// This ensures that each test can't accidentally access or modify the data
// from other tests or the application itself, and because they're in-memory,
// there's nothing that needs to be cleaned up.
Realm.Configuration.defaultConfiguration.inMemoryIdentifier =

Another way to test Realm-related code is to have all the methods you’d like to test accept a realm instance as an argument. This enables you to pass in different realms when running the app and when testing it.

For example, suppose your app has a method to GET a user profile from a JSON API. You want to test that the local profile is properly created:

// Application Code
func updateUserFromServer() {
let url = URL(string: "")
URLSession.shared.dataTask(with: url!) { data, _, _ in
let realm = try! Realm()
createOrUpdateUser(in: realm, with: data!)
public func createOrUpdateUser(in realm: Realm, with data: Data) {
let object = try! JSONSerialization.jsonObject(with: data) as? [String: String]
try! realm.write {
realm.create(User.self, value: object, update: .modified)
// Test Code
let realmPath = URL(fileURLWithPath: "...")
func testThatUserIsUpdatedFromServer() {
let config = Realm.Configuration(fileURL: realmPath)
let testRealm = try! Realm(configuration: config)
let jsonData = "{\"email\": \"\"}".data(using: .utf8)!
// In our test, we're passing in the testRealm. This is where we'd
// pass in our "real" realm in the application code above.
createOrUpdateUser(in: testRealm, with: jsonData)
XCTAssertEqual(testRealm.objects(User.self).first!.email, "",
"User was not properly updated from server.")

New in version 10.21.0.

If you want to work with a subset of an object's properties for testing, you can create a class projection. A class projection is a model abstraction where you can pass through, rename, or exclude realm object properties. While this feature simplifies view model implementation, it also simplifies testing with Realm Database.


This example uses the object models and the class projection from the Define and Use Class Projections page.

In this example, we create a realm object using the full object model. Then, we view retrieve the object as a class projection, working with only a subset of its properties.

With this class projection, we don't need to access or account for properties that we don't need to test.

func testWithProjection() {
let realm = try! Realm()
// Create a Realm object, populate it with values
let jasonBourne = Person(value: ["firstName": "Jason",
"lastName": "Bourne",
"address": [
"city": "Zurich",
"country": "Switzerland"]])
try! realm.write {
// Retrieve all class projections of the given type `PersonProjection`
// and filter for the first class projection where the `firstName` property
// value is "Jason"
let person = realm.objects(PersonProjection.self).first(where: { $0.firstName == "Jason" })!
// Verify that we have the correct PersonProjection
XCTAssert(person.firstName == "Jason")
// See that `homeCity` exists as a projection property
// Although it is not on the object model
XCTAssert(person.homeCity == "Zurich")
// Change a value on the class projection
try! realm.write {
person.firstName = "David"
// Verify that the projected property's value has changed
XCTAssert(person.firstName == "David")

Don't link the Realm framework directly to your test target. This can cause your tests to fail with an exception message "Object type 'YourObject' is not managed by the Realm." Unlinking Realm from your test target should resolve this issue.

Compile your model class files in your application or framework targets; don't add them to your unit test targets. Otherwise, those classes are duplicated when testing, which can lead to difficult-to-debug issues.

Expose all the code that you need for testing to your unit test targets. Use the public access modifier or @testable.

Since you’re using Realm as a dynamic framework, you’ll need to make sure your unit test target can find Realm. Add the parent path to RealmSwift.framework to your unit test’s “Framework Search Paths”.

Realm Studio enables you to open and edit local realms. It supports Mac, Windows and Linux.

Debugging apps using Realm's Swift API must be done through the LLDB console.

Although the LLDB script allows inspecting the contents of your realm variables in Xcode’s UI, this doesn’t yet work for Swift. Those variables will show incorrect data. Instead, use LLDB’s po command to inspect the contents of data stored in a realm.

Some developers experience build issues after installing MongoDB Realm via CocoaPods or Carthage. Common causes of these issues include:

  • Installation issues:

    • Initial install failed
    • Using an unsupported version of the dependency manager
  • Build tool issues:

    • Build tools have stale caches
    • Updating build tool versions
  • Making changes to your project setup, such as:

    • Adding a new target
    • Sharing dependencies across targets

A fix that often clears these issues is to delete derived data and clean the Xcode build folder.

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.