Merge pull request #11 from yoichiro/method_aliases

Support simple API names and add `locale` property

.gitignore

@@ -4,4 +4,5 @@ package-lock.json
 *.tgz
 .nyc_output/
 dist/
-package/
+package/
+docs/

README.md

@@ -44,7 +44,7 @@ const action = new ActionsOnGoogleAva(require('./test/test-credentials.json'));
 // Start out with giving a name to this test
 action.startTest('Facts about Google - direct cat path', action => {
     // Return a promise that starts a conversation with your test app
-    return action.startConversation()
+    return action.start()
         .then(({ textToSpeech }) => {
             // Get a response back from your fulfillment.
             // To continue the conversation, you can send
@@ -70,6 +70,17 @@ action.startTest('Facts about Google - direct cat path', action => {
 ```
 12. Run `yarn test`. You should see your test be executed.
 
+## Supported features
+
+This library provides the following features to control your conversation:
+
+* `action.start()` - Start your conversation with your action using "my test app".
+* `action.startWith()` - Start your conversation with your action using the specified action name.
+* `action.send()` - Send some phrase to your action.
+* `action.cancel()` - End your conversation. This library says "cancel".
+* `action.locale` - Set a locale for your conversation.
+* `action.location` - Set an array of a latitude and a longitude.
+
 ## Possible responses
 
 These responses will come from your fulfillment, and will consist of whatever
@@ -120,13 +131,6 @@ res
       .divider - Boolean
 ```
 
-## Additional features
-
-You can run a few different types of automated test scenarios.
-
-* `action.location = [latitude, longitude];`
-* `action.locale = 'en-US'; // Or any other supported locale`
-
 ## Known Issues
 
 * Testing transactions does not work

examples/facts-about-google-ts/test/facts-about-google.test.ts

@@ -24,7 +24,7 @@ const action: ActionsOnGoogleAva = new ActionsOnGoogleAva(require(
 // Start action and ask for history facts until there are no more history factsi
 action.startTest('Facts about Google - history path', async (action: ActionsOnGoogleAva) => {
     let appResponse: AssistResponse
-    await action.startConversation()
+    await action.start()
     appResponse = await action.send('history')
     expect(appResponse.textToSpeech[0]).to.have.string("Sure, here's a history fact.")
     appResponse = await action.send('sure')
@@ -40,7 +40,7 @@ action.startTest('Facts about Google - history path', async (action: ActionsOnGo
 // Start action and ask for headquarter facts until there are no more headquarter facts
 action.startTest('Facts about Google - headquarters path', async (action: ActionsOnGoogleAva) => {
     let appResponse: AssistResponse
-    await action.startConversation()
+    await action.start()
     appResponse = await action.send('headquarters')
     expect(appResponse.textToSpeech[0]).to.have.string("Okay, here's a headquarters fact.")
     appResponse = await action.send('sure')
@@ -54,7 +54,7 @@ action.startTest('Facts about Google - headquarters path', async (action: Action
 // Start action and ask for a cat fact right away
 action.startTest('Facts about Google - direct cat path', async (action: ActionsOnGoogleAva) => {
     let appResponse: AssistResponse
-    await action.startConversation()
+    await action.start()
     appResponse = await action.send('cats')
     expect(appResponse.textToSpeech[0]).to.have.string("Alright, here's a cat fact.")
 })
@@ -63,7 +63,7 @@ action.startTest('Facts about Google - direct cat path', async (action: ActionsO
 // then switch to provide facts about cats
 action.startTest('Facts about Google - cat path', async (action: ActionsOnGoogleAva) => {
     let appResponse: AssistResponse
-    await action.startConversation()
+    await action.start()
     appResponse = await action.send('headquarters')
     expect(appResponse.textToSpeech[0]).to.have.string("Okay, here's a headquarters fact.")
     appResponse = await action.send('sure')

examples/facts-about-google/test/facts-about-google.test.js

@@ -34,7 +34,7 @@ const action = new ActionsOnGoogleAva(require('../../../test-credentials.json'))
 
 // Start action and ask for history facts until there are no more history facts
 action.startTest('Facts about Google - history path', action => {
-    return action.startConversation()
+    return action.start()
         .then((res) => {
             return action.send('history')
         })
@@ -61,7 +61,7 @@ action.startTest('Facts about Google - history path', action => {
 
 // Start action and ask for headquarter facts until there are no more headquarter facts
 action.startTest('Facts about Google - headquarters path', action => {
-    return action.startConversation()
+    return action.start()
         .then(({ textToSpeech }) => {
             return action.send('headquarters')
         })
@@ -84,7 +84,7 @@ action.startTest('Facts about Google - headquarters path', action => {
 
 // Start action and ask for a cat fact right away
 action.startTest('Facts about Google - direct cat path', action => {
-    return action.startConversation()
+    return action.start()
         .then(({ textToSpeech }) => {
             return action.send('cats');
         })
@@ -96,7 +96,7 @@ action.startTest('Facts about Google - direct cat path', action => {
 // Start action and ask for headquarters until there are no more headquarter facts,
 // then switch to provide facts about cats
 action.startTest('Facts about Google - cat path', action => {
-    return action.startConversation()
+    return action.start()
         .then(({ textToSpeech }) => {
             return action.send('headquarters')
         })

examples/number-genie/test/number-genie.test.js

@@ -34,7 +34,7 @@ const action = new ActionsOnGoogleAva(require('../../../test-credentials.json'))
 
 // Should start action, presetting the answer to fifty. Then guess a few times until the answer is 50.
 action.startTest('Number Genie - should guess the right answer', action => {
-    return action.startConversation('about 50')
+    return action.start('about 50')
         .then(({ displayText, cards }) => {
             expect(displayText[0]).to.have.string("I'm thinking of a number from 0 to 100.");
             expect(displayText[1]).to.be.equal("What's your first guess?");
@@ -66,7 +66,7 @@ action.startTest('Number Genie - should guess the right answer', action => {
 
 // Should start action, presetting the answer to a number higher than the range 0-100
 action.startTest('Number Genie - starts with invalid number', action => {
-    return action.startConversation('about 250')
+    return action.start('about 250')
         .then(({ displayText }) => {
             expect(displayText[0]).to.have.string("Woah there! I can't use that number.");
             expect(displayText[1]).to.be.equal("What's your first guess?");
@@ -82,7 +82,7 @@ action.startTest('Number Genie - starts with invalid number', action => {
 
 // Should start action using the French locale, and confirm the response is also in French
 action.startTest('Number Genie French', action => {
-    action.setLocale('fr-FR');
+    action.locale = 'fr-FR';
     return action.send('parle avec mon application test') // Talk to my test app
         .then(({ displayText, cards }) => {
             expect(displayText[1]).to.be.equal("Quel est votre premier essai ?");

package.json

@@ -10,10 +10,12 @@
         "node": ">=6.0.0"
     },
     "scripts": {
-        "clean": "rm -rf dist",
+        "clean": "rm -rf dist docs",
         "lint": "tslint -p .",
         "build": "tsc && cp -r ./locales ./dist",
-        "test": "yarn clean && yarn build && yarn lint && nyc ava --fail-fast dist/test/test.js"
+        "test": "yarn clean && yarn build && yarn lint && nyc ava --fail-fast dist/test/test.js",
+        "docs": "typedoc --options typedoc.json",
+        "docs:clean": "rm -rf docs && mkdir docs && touch docs/.nojekyll && yarn docs"
     },
     "repository": {
         "type": "git",
@@ -53,6 +55,7 @@
         "sinon": "^6.0.0",
         "tslint": "^5.9.1",
         "tslint-eslint-rules": "^5.1.0",
+        "typedoc": "^0.11.1",
         "typescript": "^2.7.2",
         "winston": "2.2.0"
     }

src/actions-on-google.ts

@@ -260,7 +260,14 @@ export class ActionsOnGoogle {
         return client
     }
 
+    /**
+     * @deprecated This will be removed in future releases. Use `action.locale` instead.
+     */
     setLocale(l: string) {
+        this.locale = l
+    }
+
+    set locale(l: string) {
         if (SUPPORTED_LOCALES.concat(Object.keys(FALLBACK_LOCALES)).indexOf(l) === -1) {
             console.warn(`Warning: Unsupported locale '${l}' in this tool. Ignore.`)
         }
@@ -276,18 +283,39 @@ export class ActionsOnGoogle {
         }
     }
 
+    /**
+     * @deprecated This will be removed at releasing a version 1.
+     */
     startConversation(prompt?: string) {
-        return this.startConversationWith(this.i18n_('my_test_app'), prompt)
+        return this.start(prompt)
     }
 
+    start(prompt?: string) {
+        return this.startWith(this.i18n_('my_test_app'), prompt)
+    }
+
+    /**
+     * @deprecated This will be removed at releasing a version 1.
+     */
     startConversationWith(action: string, prompt?: string) {
+        return this.startWith(action, prompt)
+    }
+
+    startWith(action: string, prompt?: string) {
         const query = prompt
             ? this.i18n_('start_conversation_with_prompt', { app_name: action, prompt })
             : this.i18n_('start_conversation', { app_name: action })
         return this.send(query)
     }
 
+    /**
+     * @deprecated This will be removed at releasing a version 1.
+     */
     endConversation() {
+        return this.cancel()
+    }
+
+    cancel() {
         return this.send(this.i18n_('cancel'))
     }
 
@@ -496,4 +524,4 @@ export class ActionsOnGoogle {
             conversation.end()
         })
     }
-}
+}

src/test/test.ts

@@ -88,7 +88,7 @@ test.serial('sends correct request parameters - en-US', t => {
     }
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then(res => {
       t.pass()
       mockResponse.restore()
@@ -123,11 +123,11 @@ test.serial('sends correct request parameters - fr-FR', t => {
     }
   })
 
-  action.setLocale('fr-FR')
-  return action.startConversation('')
+  action.locale = 'fr-FR'
+  return action.start('')
     .then(res => {
       t.pass()
-      action.setLocale('en-US')
+      action.locale = 'en-US'
       mockResponse.restore()
     })
 })
@@ -140,7 +140,7 @@ test.serial('opens and exits action', t => {
     return conversation
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then((res: AssistResponse) => {
       t.deepEqual(res, Sample.NUMBER_GENIE_WELCOME_VALUES)
       mockResponse.restore()
@@ -155,7 +155,7 @@ test.serial('verifies parsing closing response of conversation', t => {
     return conversation
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then((res: AssistResponse) => {
       t.is(res.textToSpeech[0],
         '<speak>OK, I\'m already thinking of a number for next time.</speak>')
@@ -173,7 +173,7 @@ test.serial('verifies parsing textToSpeech, displayText, suggestions', t => {
     return conversation
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then((res: AssistResponse) => {
       t.is(res.textToSpeech[0], 'Hi there!')
       t.is(res.textToSpeech[1], 'I can show you basic cards, lists and carousels as well as ' +
@@ -195,7 +195,7 @@ test.serial('verifies parsing basic cards', t => {
     return conversation
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then((res: AssistResponse) => {
       const basicCard = res.cards![0]
       t.is(basicCard.title, 'Title: this is a title')
@@ -222,7 +222,7 @@ test.serial('verifies parsing a browse carousel', t => {
     return conversation
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then((res: AssistResponse) => {
       const firstItem = res.carousel![0]
       const secondItem = res.carousel![1]
@@ -246,7 +246,7 @@ test.serial('verifies parsing a carousel', t => {
     return conversation
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then((res: AssistResponse) => {
       const firstItem = res.carousel![0]
       t.is(res.carousel!.length, 4)
@@ -275,7 +275,7 @@ test.serial('verifies parsing a list', t => {
     return conversation
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then((res: AssistResponse) => {
       const firstItem = res.list!.items[0]
       t.is(res.list!.items.length, 4)
@@ -305,7 +305,7 @@ test.serial('verifies parsing a media response', t => {
     return conversation
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then((res: AssistResponse) => {
       t.is(res.mediaResponse!.type, 'AUDIO')
       t.is(res.mediaResponse!.name, 'Jazz in Paris')
@@ -326,7 +326,7 @@ test.serial('verifies parsing a linkout suggestion', t => {
     return conversation
   })
 
-  return action.startConversation('')
+  return action.start('')
     .then((res: AssistResponse) => {
       t.is(res.linkOutSuggestion!.url, 'https://assistant.google.com/')
       t.is(res.linkOutSuggestion!.name, 'Suggestion Link')
@@ -342,7 +342,7 @@ test.serial('verifies parsing a table', t => {
     return conversation
   })
 
-  return action!.startConversation('')
+  return action!.start('')
     .then((res: AssistResponse) => {
       t.deepEqual(res.table!.headers, ['header 1', 'header 2', 'header 3'])
       t.deepEqual(res.table!.rows[0].cells, ['row 1 item 1', 'row 1 item 2', 'row 1 item 3'])

typedoc.json

@@ -0,0 +1,12 @@
+{
+  "out": "docs",
+  "exclude": [
+    "**/test/**/*.*",
+    "**/index.ts"
+  ],
+  "ignoreCompilerErrors": true,
+  "disableOutputCheck": true,
+  "excludeExternals": true,
+  "excludePrivate": true,
+  "excludeNotExported": true
+}