This project is a resource for developers who want to build iOS apps that make use of Rust libraries.
The ios-test-harness Xcode project in this repo provides an iOS-based test framework that can be used similar to the standard Rust test framework. It expects the crate being tested to provide a static library with a single extern C entrypoint with the signature void test(). When run in the simulator (or on an iOS device), the test harness puts up a single screen with a Run Test button that can be used to invoke the test() entry. When run via the Xcode Project>Test menu, the test harness invokes the test() entry as part of the test sequence.
The idea is to have your test() entry run the same series of tests that you would run via the Rust test harness. If the tests pass without panic, the run is successful.
The test harness can be used on your own crates simply by cloning it locally and creating an appropriate test-spec.sh file at the top level of the project which declares where your crate is and how to build the test library. You can copy the test-spec.sample.sh file to test-spec.sh in order to get started. Detailed instructions are in the next section.
Because Apple remembers which developers have registered which bundle ids, to use this test harness you will have to go into XCode and change its bundle ID and signing information. When you open the test harness project, XCode may recommend that you update your script sandbox settings…don’t! This will prevent the test harness from accessing your crate directory.
To use this test harness, you must create a test-spec.sh shell script. There are five shell variables in the test-spec.sh script that you set in order for this test harness to work:
CRATE_PATHmust be defined as a full path to the directory containing the crate you want to test.CRATE_FEATURESgives a comma-separated list of crate features (other than the default) that must be defined when compiling your test library. If there are no such features, define it as the empty string (“”). There is currently no way to disable the default features of the crate being tested.CRATE_PACKAGEgives the name of the package (if any) whose build will produce your test library. If there is no such package, define it as the empty string.CRATE_EXAMPLEgives the name of the example (if any) whose build will produce your test library. If there is no such example, define it as the empty string.LIBRARY_NAMEgives the name of the library
If both CRATE_PACKAGE and CRATE_EXAMPLE are specified, the build will specify both, and the library will be assumed to be created by the example. If neither are specified, the test harness will assume that your crate contains only one package and that building it will build the library.
This test harness can be used to test both debug and release builds of your crate. Running the test harness in the Debug configuration will do a debug build of your library, and similarly for Release.
The XCode target of your build (e.g., an ios device or an ios simulator) will be used to pick an appropriate target platform for your rust library build. You must have installed the appropriate target support on your machine.
NOTE: This test harness assumes you have done a standard install of Rust using rustup and sets the PATH variable based on that when building your test library.
For example: The test-spec.sample.sh file that comes with this project assumes that the directory containing the ios-test-harness.xcodeproj bundle (that is, the top level of this repository) is adjacent to the directory containing the crate being tested (called keyring-rs), and that the test library is an example in that crate.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.