const Corellium = require('corellium-api').Corellium;

Sets up a new Corellium endpoint to use. Accepted options are:

• options.endpoint: the URL of the endpoint to use
• options.username: username to use for login
• options.password: password for given username

Example:

let corellium = new Corellium({
    endpoint: 'https://client.corellium.com',
    username: 'admin',
    password: 'password'
});

Performs the login on the endpoint using the credentials passed through the constructor.

Example:

await corellium.login();

Returns all projects from the connected endpoint as an Array.

Example:

let projects = await corellium.projects();
let project = projects.find(project => project.name === "Demo Project");

Line 2 shows how to pick a specific project from the returned map.

Returns the Project with the identifier projectId or undefined if it does not exist.

Example:

let project = await corellium.getProject('b5ef6be5-71a9-4a26-a320-9be182217ac8
');

Returns the Project with the name name or undefined if it does not exist.

Example:

let project = await corellium.projectNamed('Default Project');

Returns an Array with all devices that are supported by the endpoint, with their supported firmwares.

Example:

let supported = await corellium.supported();

Note: Instances of the class Project are supposed to be created using the Corellium#projects(), Corellium#getProject(), or Corellium#projectNamed() methods.

Returns the name of the project.

Example:

let name = project.name;

Returns the quotas of the project. Currently, quotas' only element is cpus.

Example:

// Create map of supported devices.
let supported = {};
(await corellium.supported()).forEach(modelInfo => {
    supported[modelInfo.name] = modelInfo;
});

// Get how many CPUs we're currently using.
let cpusUsed = 0;
instances.forEach(instance => {
    cpusUsed += supported[instance.flavor].quotas.cpus;
});

console.log('Used: ' + cpusUsed + '/' + project.quotas.cpus);

Returns an Array of Instance objects of all virtual machine instances.

Example:

let instances = await project.instances();
let instance = instances.find(instance => instance.name === 'Test-Device');

Line 2 shows how to select a specific instance by name from the returned instances.

Returns the instance identified by id.

Example:

let instance = project.getInstance('a9212122-40b0-1387-7feb-7a721916580d');

Creates a new instance with the given options. The following options are supported:

• options.name: The name of the new Instance.
• options.flavor: The flavor of the Instance that is being created. Currently, the following flavors are supported:
  • ranchu for Android devices
  • iphone6
  • iphone6plus
  • iphone6s
  • iphone6splus
  • iphone7
  • iphone7plus
  • iphonese
  • iphone8
  • iphone8plus
  • iphonex
  • ipodtouch6
  • ipadmini4wifi
• options.os: The software version, e.g. 11.3.1 for iOS, or 11.0.0 for Android
• options.patches: The following values are supported:
  • jailbroken The instance should be jailbroken (default).
  • nonjailbroken The instance should not be jailbroken.

Example:

// create instance
let instance = await project.createInstance({
    'name': 'Test Device',
    'flavor': 'ranchu',
    'os': '11.0.0'
});
// wait for the instance to finish restoring
await instance.finishRestore();

Note: instances of class Instance are only supposed to be retrieved by Project#instances(), Project#getInstance(), or Project#createInstance.

The name of the instance.

Example:

let instances = await project.instances();
let instance = instances[0];
console.log("Using " + instance.name);

Returns the state of the Instance.

Valid states are:

• on: The Instance is running.
• off: The Instance is not running.
• creating: The Instance is being created.
• deleting: The Instance is being deleted.

Example:

await instance.start();
await instance.waitForState('on');
assert.equal(instance.state, 'on');

See also: Instance.waitForState()

Returns the flavor of the Instance.

Example:

let instances = await project.instances();
instances.forEach(instance => {
    console.log(instance.name + ': ' + instance.flavor);
});

Renames an Instance to name.

Example:

let instances = await project.instances();
let instance = instances.find(instance => instance.name === 'Test-Device');
await instance.rename('Demo-Device');

Returns an Array of Snapshot objects with the snapshots for the current Instance.

Example:

let snapshots = instance.snapshots();
snapshots.forEach(snapshot => {
    console.log(snapshot.name, snapshot.created);
});

Creates a snapshot named name of an Instance. Returns an instance of Snapshot.

Example:

await instance.takeSnapshot('before-test');

Returns the current console log of an Instance.

Example:

console.log(await instance.consoleLog());

Returns recorded panics of an Instance.

Example:

console.log(await instance.panics());

See also: Event: panic

Clears recorded panics of an Instance.

Example:

await instance.clearPanics();

See also: Event: panic

Returns an Agent instance for the Instance.

Example:

let agent = await instance.agent();
await agent.ready();

Creates an additional Agent connection to the Instance. This is required for agent tasks that do not actually finish, like Agent#crashes().

Example:

let crashListener = await instance.newAgent();
crashListener.crashes('com.corellium.demoapp', (err, crashReport) => {
    if (err) {
        console.error(err);
        return;
    }
    console.log(crashReport);
});

Returns a node stream for the Instance's console.

Example:

let consoleStream = await instance.console();
consoleStream.pipe(process.stdout);

Starts an Instance.

Example:

await instance.start();

Stops an Instance.

Example:

await instance.stop();

Reboots an Instance.

Example:

await instance.reboot();

Destroys an Instance.

Example:

// delete all instances of the project
let instances = await project.instances();
instances.forEach(instance => {
    instance.destroy();
});

Instructions the Instance to create a screenshot of the device screen. Returns a Buffer with PNG data.

Example:

let screenshot = instance.takeScreenshot();
fs.writeFileSync('screenshot.png', screenshot);

Waits for a device to finish restoring.

Example:

await instance.finishRestore();

See also the example at Project#createInstance()

Waits for the Instance to switch to a specific state. For valid states, see Property: state.

Example:

await instance.waitForState('on');

Instance emits a change event when its info changes, e.g. when the instance is renamed or its state changes.

Example:

instance.on('change', async () => {
    console.log(instance.id, instance.name, instance.state);
});

Instance emits a panic event when a panic occurred.

Example:

instance.on('panic', async () => {
    console.log('Panic detected!');

    // get the panic log(s)
    console.log(await instance.panics());

    // Download the console log.
    console.log(await instance.consoleLog());

    // Clear the panic log.
    await instance.clearPanics();

    // Reboot the instance.
    await instance.reboot();
});

Note: Instances of the class Agent are only supposed to be retrieved with Instance#agent() or Instance#newAgent().

Waits for the agent to be ready to use. This essentially means that it will wait until Springboard has launched.

Example:

let agent = await instance.agent();
await agent.ready();

Returns an Array of installed apps.

Example:

let appList = await agent.appList();
for (app of appList) {
    console.log('Found installed app ' + app['bundleID']);
}

Launches the app with the given bundleID.

Example:

await agent.run("com.corellium.demoapp");

Kills the underlying process of the app identified by bundleID.

Example:

await agent.kill("com.corellium.demoapp");

Installs an app, where the packaged app needs to be available on the VMs filesystem at path. The optional progress parameter expects a callback function with signature (progress, status), where progress is the percentage as float, and status a string with the current status of the installation progress.

To upload a file to the VM's filesystem, see Agent#upload().

See also Agent#installFile() which will handle the file upload on its own.

Example:

await agent.install('/var/tmp/temp.ipa', (progress, status) => {
    console.log(progress, status);
});

Uploads the packaged app provided through the node stream object stream and installs it on the VM. The optional progress parameter expects a callback function with signature (progress, status), where progress is the percentage as float, and status a string with the current status of the installation progress.

Example:

await agent.installFile(fs.createReadStream('test.ipa'), (progress, status) => {
    console.log(progress, status);
});

Uninstalls the app identified by bundleID. The optional progress parameter expects a callback function with signature (progress, status), where progress is the percentage as float, and status a string with the current status of the uninstallation progress.

Example:

await agent.uninstall('com.corellium.demoapp', (progress, status) => {
    console.log(progress, status);
});

Returns a temporary random filename on the VMs filesystem that by the time of invocation of this method is guaranteed to be unique.

See example at Agent#upload().

Example:

let tmpName = await agent.tempFile();
await agent.upload(tmpName, fs.createReadStream('test.ipa'));

Downloads the file at path from the VM's filesystem. Returns a node stream object.

Example:

let dl = agent.download('/var/tmp/test.log');
dl.pipe(fs.createWriteStream('test.log'));

Deletes the file at path on the VM's filesystem.

Example:

await agent.deleteFile('/var/tmp/test.log');

Subscribes to crash events for a given app identified by bundleID. The callback will be called as soon as the agent found a new crash log. The signature is (err, crashReport) where err is only defined if an error occured setting up or watching for crash logs and crashReport will contain the full crash report data.

Currently this is only available on iOS virtual devices.

Note: Since this method blocks the communication channel of the agent to wait for crash reports, a new Agent connection should be created with Instance#newAgent().

Example:

let crashListener = await instance.newAgent();
crashListener.crashes("com.corellium.demoapp", (err, crashReport) => {
    if (err) {
        console.error(err);
        return;
    }
    console.log(crashReport);
});

Locks the device software-wise.

Example:

await agent.lockDevice();

Unlocks the device software-wise.

Example:

await agent.unlockDevice();

Disconnects an Agent connection. This is usually only required if a new agent connection has been created and is no longer needed, for example if the crashListener demonstrated in the example at Agent#crashes() is not required anymore.

Example:

// subscribe for crash logs
let crashListener = await instance.newAgent();
crashListener.crashes("com.corellium.demoapp", (err, crashReport) => {
    if (err) {
        console.error(err);
        return;
    }
    console.log(crashReport);
});

// wait 15 seconds
let timeoutComplete = null;
new Promise(resolve => {
    timeoutComplete = resolve;
    setTimeout(timeoutComplete, 15000);
});

// crashListener not required anymore
crashListener.disconnect();

Note: Instances of the class Snapshot are only supposed to be retrieved with Instance#snapshots() or Instance#takeSnapshot().

Name of the snapshot.

The time the snapshot was created.

Tells wether a snapshot is fresh or not.

A snapshot will be automatically created after the initial restore of an Instance in which case it is considered fresh.

Example:

let snapshots = await instance.snapshots();
let freshSnapshot = snapshots.find(snapshot => snapshot.fresh);
await freshSnapshot.restore();

Renames a snapshot to name.

Example:

let snapshots = await instance.snapshots();
let snapshot = snapshots.find(snapshot => snapshot.name === 'Test 1');
if (snapshot) {
    await snapshot.rename('Test 1 new');
}

Restores a snapshot.

Example:

let snapshots = await instance.snapshots();
let snapshot = snapshots.find(snapshot => snapshot.name === 'Pre-Test 1');
if (snapshot) {
    await snapshot.restore();
}

Deletes a snapshot.

Example:

let snapshots = await instance.snapshots();
snapshots.forEach(snapshot => {
    console.log("Deleting snapshot " + snapshot.name)
    snapshot.delete();
});