feat: CORE-13681 - update getInstance to bypass throwing on instance on

Author: Judy Lin

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corellium/corellium-api",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "Supported nodejs library for interacting with the Corellium service and VMs",
   "main": "src/corellium.js",
   "husky": {

src/corellium.js

@@ -468,21 +468,39 @@ class Corellium {
     })
   }
 
+  /**
+   * @typedef {Object} GetInstanceOpts
+   * @property {string} id - instanceId
+   * @property {boolean} [throwIfNotOn=true] - Optional boolean property to not throw if the instance is off (defaults to true)
+   */
+
   /**
    * Attempts to retrieve Instance by iterating through all projects until the instance is found.
    *
-   * @param {string} instanceId
+   * @param {string | GetInstanceOpts} opts - Either an instanceId string or an object with an `id` string and optional `throwIfNotOn` boolean (defaults to true if omitted)
    * @returns {Promise<Instance>}
    * @example
    * await corellium.getInstance('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa')
+   * @example
+   * await corellium.getInstance({ id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', throwIfNotOn: false })
+   * @example
+   * await corellium.getInstance({ id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa' })
    */
-  async getInstance (instanceId) {
+  async getInstance (opts) {
     let lastError
+    let id, throwIfNotOn
+    if (typeof opts === 'string') {
+      id = opts
+      throwIfNotOn = true
+    } else {
+      ({ id, throwIfNotOn = true } = opts)
+    }
+
     const projects = await this.projects()
     for (const project of projects) {
       try {
-        const instance = await project.getInstance(instanceId)
-        if (instance.info.state !== 'on') {
+        const instance = await project.getInstance(id)
+        if (throwIfNotOn && (instance.info.state !== 'on')) {
           throw new Error('The instance is not turned on')
         }
         return instance
@@ -495,7 +513,7 @@ class Corellium {
       }
     }
 
-    throw lastError || new Error(`Could not retrieve instance!  instanceId=${instanceId}`)
+    throw lastError || new Error(`Could not retrieve instance!  instanceId=${id}`)
   }
 }
 

test/integration-tests.js

@@ -42,10 +42,10 @@ describe('Corellium API', function () {
   let INSTANCE_VERSIONS = []
   if (CONFIGURATION.testFlavor === 'ranchu') {
     this.slow(10000)
-    this.timeout(20000)
+    this.timeout(60000)
 
     BASE_LIFECYCLE_TIMEOUT = 40000
-    BASE_SNAPSHOT_TIMEOUT = 20000
+    BASE_SNAPSHOT_TIMEOUT = 60000
     INSTANCE_VERSIONS = ['7.1.2', '8.1.0', '9.0.0', '10.0.0', '11.0.0', '12.0.0']
   } else {
     this.slow(40000)
@@ -185,6 +185,12 @@ describe('Corellium API', function () {
       assert(foundInstance.id === instance.id)
     })
 
+    it('can get instance and bypass instance on error', async function () {
+      const instance = instanceMap.get(INSTANCE_VERSIONS[0])
+      const foundInstance = await corellium.getInstance({ id: instance.id, throwIfNotOn: false })
+      assert(foundInstance.id === instance.id)
+    })
+
     // Not visible to cloud users with one project:
     it('can add and remove keys', async function () {
       const keyInfo = await project