Running Tests

Couchbase Lite now uses the standard XCTest framework that's integrated into Xcode. We'll assume you already know how to run tests in Xcode; if not, please see the Xcode user documentation.

However, the replication tests require that a Sync Gateway instance be running, and serving some specific databases, so there's a bit of setup to do before you press Cmd-U...

Starting The Server For Replication Tests

(If you're not going to be running any of the replicator or change-tracker tests, you can skip this.)

1. Install the latest release of Sync Gateway (you don't need the source code.)
2. In a shell, go to the Unit-Tests/Server directory in the CBL source tree (cd Unit-Tests/Server)
3. sync_gateway cbl_unit_tests.json
4. Open another shell and go to Unit-Tests/Server
5. sync_gateway cbl_unit_tests_ssl.json

Running Tests

• To test the Mac OS build, select the "CBL Mac" scheme
• To test the iOS build in the simulator, select the "CBL iOS Test App" scheme and a simulator device

Then choose the Product > Test menu command (or press Cmd-U).

Basic logging (equivalent to the -Log YES option) is always enabled while testing. If you want to add extra Logging options, use Xcode's args-configuration UI (see below.)

Testing on real iOS devices

Testing on a device is more complicated because the replication tests will need to know the IP address or hostname of your Mac, to connect to the Sync Gateway. You configure this by setting the following environment variables at runtime:

    CBL_TEST_SERVER :    The base URL of the server (defaults to http://127.0.0.1:5984/)
    CBL_SSL_TEST_SERVER : The base URL of the server that's running SSL (defaults to https://127.0.0.1:4994/)

If you're just using your development Mac as a server and it doesn't have a static hostname or IP address, you can use its Bonjour hostname, like jens.local. (See the Sharing system pref pane to find or configure this.)

Unfortunately the tests that connect to the SSL server will fail due to a hostname mismatch, since the server cert is made out to localhost, not jens.local or whatever. You can just ignore this. Actually making them work will require creating a new server cert with the correct hostname, and installing it in the Unit-Tests/Server directory (replacing cert.pem and privkey.pem.)

How To Configure Command-Line Arguments and Environment Variables

1. Press Cmd-Option-U, which is an optional form of the Test command that brings up the scheme's test settings.
2. In the sheet, click the "Arguments" tab.
3. Click the "+" button below the "Arguments" list to add an argument (or multiple args separated by spaces, e.g. -Log YES).
4. Click the "+" button below the "Environment Variables" list to add a variable.

Pro tip: You can temporarily disable these by unchecking them.

How To Write New Tests

The unit tests are located in the top-level "Unit Tests" folder/group in the project window. Pick the appropriate test class and add a new test-case method.

Note that most of these classes inherit from CBLTestCase or CBLTestCaseWithDB, which are subclasses of XCTestCase that add extra behavior and utilities.