README

iOS Utility Library

This is a library of utilities for dealing programmatically with iOS applications, used namely for tools like Hyperloop and Titanium.

ioslib supports Xcode 6 and newer.

Prerequisites

This library current depends on node-ios-device which supports Node.js 0.10 and Node 4.x through 8.x.

Installation

From NPM:

npm install ioslib

From GitHub:

npm install git://github.com/appcelerator/ioslib.git

Examples

Detect all the connected iOS devices:

var ioslib = require('ioslib');

ioslib.device.detect(function (err, devices) {
    if (err) {
        console.error(err);
    } else {
        console.log(devices);
    }
});

Install an application on device

var deviceUDID = null; // string or null to pick first device

ioslib.device.install(deviceUDID, '/path/to/name.app', 'com.company.appname')
    .on('installed', function () {
        console.log('App successfully installed on device');
    })
    .on('appStarted', function () {
        console.log('App has started');
    })
    .on('log', function (msg) {
        console.log('[LOG] ' + msg);
    })
    .on('appQuit', function () {
        console.log('App has quit');
    })
    .on('error', function (err) {
        console.error(err);
    });

Launch the iOS Simulator

ioslib.simulator.launch(null, function (err, simHandle) {
    console.log('Simulator launched');
    ioslib.simulator.stop(simHandle, function () {
        console.log('Simulator stopped');
    });
});

Launch, install, and run an application on simulator

var simUDID = null; // string or null to pick a simulator

ioslib.simulator.launch(simUDID, {
        appPath: '/path/to/name.app'
    })
    .on('launched', function (msg) {
        console.log('Simulator has launched');
    })
    .on('appStarted', function (msg) {
        console.log('App has started');
    })
    .on('log', function (msg) {
        console.log('[LOG] ' + msg);
    })
    .on('error', function (err) {
        console.error(err);
    });

Force stop an application running on simulator

ioslib.simulator.launch(simUDID, {
        appPath: '/path/to/name.app'
    })
    .on('launched', function (simHandle) {
        console.log('Simulator launched');
        ioslib.simulator.stop(simHandle).on('stopped', function () {
            console.log('Simulator stopped');
        });
    });

Find a valid device/cert/provisioning profile combination

ioslib.findValidDeviceCertProfileCombos({
    appId: 'com.company.appname'
}, function (err, results) {
    if (err) {
        console.error(err);
    } else {
        console.log(results);
    }
});

Detect everything

ioslib.detect(function (err, info) {
    if (err) {
        console.error(err);
    } else {
        console.log(info);
    }
});

Detect iOS certificates

ioslib.certs.detect(function (err, certs) {
    if (err) {
        console.error(err);
    } else {
        console.log(certs);
    }
});

Detect provisioning profiles

ioslib.provisioning.detect(function (err, profiles) {
    if (err) {
        console.error(err);
    } else {
        console.log(profiles);
    }
});

Detect Xcode installations

ioslib.xcode.detect(function (err, xcodeInfo) {
    if (err) {
        console.error(err);
    } else {
        console.log(xcodeInfo);
    }
});

Running Tests

For best results, connect an iOS device.

To run all tests:

npm test

To see debug logging, set the DEBUG environment variable:

DEBUG=1 npm test

To run a specific test suite:

npm run-script test-certs

npm run-script test-device

npm run-script test-env

npm run-script test-ioslib

npm run-script test-provisioning

npm run-script test-simulator

npm run-script test-xcode

Known Issues

Simulator tests fail due to issue with NSLog() calls not properly being logged and thus we don't know when tests are done. The result is the tests timeout.

Reporting Bugs or Submitting Fixes

If you run into problems, and trust us, there are likely plenty of them at this point -- please create an Issue or, even better, send us a pull request.

Contributing

ioslib is an open source project. ioslib wouldn't be where it is now without contributions by the community. Please consider forking ioslib to improve, enhance or fix issues. If you feel like the community will benefit from your fork, please open a pull request.

To protect the interests of the ioslib contributors, Appcelerator, customers and end users we require contributors to sign a Contributors License Agreement (CLA) before we pull the changes into the main repository. Our CLA is simple and straightforward - it requires that the contributions you make to any Appcelerator open source project are properly licensed and that you have the legal authority to make those changes. This helps us significantly reduce future legal risk for everyone involved. It is easy, helps everyone, takes only a few minutes, and only needs to be completed once.

You can digitally sign the CLA online. Please indicate your email address in your first pull request so that we can make sure that will locate your CLA. Once you've submitted it, you no longer need to send one for subsequent submissions.

Contributors

The original source and design for this project was developed by Jeff Haynie (@jhaynie).

ioslib

Usage no npm install needed!