Test and Debug - iOS SDK

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.")

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.


Run these commands in the terminal, in the root of your project:

pod cache clean Realm
pod cache clean RealmSwift
pod deintegrate || rm -rf Pods
pod install --repo-update --verbose
# Assumes the default DerivedData location:
rm -rf ~/Library/Developer/Xcode/DerivedData

With your project open in Xcode, go to the Product drop-down menu, and select Clean Build Folder.

Give Feedback