actions-tools
v0.8.0
Published
This provides some useful tools to build your actions for Google Assistant.
Downloads
126
Maintainers
Readme
actions-tools
This provides you some useful tools to build your actions for the Google Assistant. Currently, the following tools provided:
- setup - This tool allows you to set up your credential to work other tools.
- interactive - This tool provides you to do a conversation between the Google Assistant and you in your terminal.
- autopilot - This tool allows you to talk with the Google Assistant automatically with phrases you prepared in advance.
- test - This tool allows you to test your action talking with the Google Assistant.
How to Install
Install this with either npm install actions-tools -g
or yarn global add actions-tools
.
How to Use: setup
First, you have to prepare your credential with the setup tool before using other tools. The preparation consists of some steps.
- Create a new project on Actions on Google.
- Download OAuth 2.0 credential file.
- Enable the Google Assistant API.
- Convert the credential file.
Create a new project
To use this, you need to create a new project on Actions on Google.
- Visit the Actions on Google console.
- Click the
Add/import project
button. - Fill in your project name, and click
CREATE PROJECT
button.
Download credential file
Then, register a new device to your project, and download a credential file.
- In the next page, there is a "Device registration" item in the bottom of the page. Click it.
- Click the
REGISTER MODEL
button. The Register model dialog should be opened. - Fill in each field as like the following, then click the
REGISTER MODEL
button.- Product name - Any product name (ex. “my product”)
- Manufacturer name - Any manufacturer name (ex. “my company”)
- Device type - Light (Of course, you can select other item)
- In the next page on the dialog, click the
Download credentials.json
button. - Specify the directory you want to save the file. The
credentials.json
file downloaded. - Click the
NEXT
button, and click theSKIP
button on the next page.
You should got the OAuth 2.0 credential file by doing the steps above.
Enable Google Assistant API
This uses the Google Assistant API to communicate with the Google Assistant. You need to turn on the Google Assistant API for your project that you created at previous step.
Do the following step to enable the Google Assistant API:
- Open your Web browser, and access to the following URL.
- https://console.cloud.google.com/apis/library/embeddedassistant.googleapis.com?q=Assistant
- If your target project is not selected, select the target project you created at the previous step on the top of the page.
- Click the
ENABLE
button to turn on the Google Assistant API.
Convert credential file
Next, you need to convert the downloaded file with the setup tool. In your terminal, execute the following command:
$ cd <YOUR_FAVORITE_DIRECTORY>
$ actions-tools setup -s <YOUR_DOWNLOADED_FILE_PATH>
- YOUR_FAVORITE_DIRECTORY - You can specify any directory to work this setting up.
- YOUR_DOWNLOADED_FILE_PATH - This is a file path of the file you downloaded at the previous step.
The setup tool can accept the following options:
-s
or--source
- The OAuth 2.0 credential file path that you downloaded from the Actions on Google. Required.-o
or--output
- The converted file path. If omitted, the<USER_HOME>/.actions-tools/credentials.json
file path is applied.
After the execution of the setup tool, you will see the URL that the setup tool generated. Copy the URL, then open your Web browser and open the URL.
$ actions-tools setup -s ./client_secret_12345.json
Go to the following URL to authorize in your Web browser, then paste the code below:
https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fassistant-sdk-prototype&response_type=code&client_id=115...61cl.apps.googleusercontent.com&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
Authorization code:
In your Web browser, authenticate your Google Account and authorize an access to the Google Assistant API. Finally, you will see the authorization code. Copy the code.
Back to your terminal, paste the authorization code. Then, the converted credentials.json
file (or the file name you specified by the -o
option) should be created.
How to Use: interactive
The interactive tool allows you to talk to the Google Assistant in your terminal. When you're developing your action, you can talk to your action immediately.
To use the interactive tool, execute the following command in your terminal:
$ actions-tools interactive
The interactive tool can accept the following options:
-c
or--credential
- The file path of the converted credential JSON file. If omitted, the<USER_HOME>/.actions-tools/credentials.json
is applied.-l
or--locale
- The locale used during conversation with the Google Assistant. If omitted, theen-US
is applied.-v
or--level
- The output level. You can specify eithersimple
anddebug
. If thesimple
selected,displayText
strings will be outputted. Otherwise, all structures that consists of the response from the Google Assistant will be outputted. If omitted, thesimple
is applied.-s
or--screen
- If you want to support the screen surface in addition to the audio, you use this option. You can specify eitheroff
,file
andplay
. If omitted, theoff
is applied.off
- Not support the screen surface.file
- Save the response data to the file in the specified directory by the-o
option.play
- Not onlyfile
, but also open the screen out data with your Web browser (Actually, the response data is passed to theopen
command. See opn).
-a
or--audio
- If you want to store and/or play the audio, you use this option. You can specify eitheroff
,file
andplay
. If omitted, theoff
is applied.off
- Do nothing.file
- Save the response data to the file in the specified directory by the-o
option.play
- Not onlyfile
, but also play the audio out data (Actually, a command you have will be used to play the MP3 file. See play-sound).
-o
or--output
- This option is required when the-s
and/or-a
option are specified and the value isfile
orplay
. You can specify the directory path where each response screen out data is written as a file. If omitted, the./
value is applied.-r
or--rich
- Turn on/off the rich output (color and emoji). If omitted, thetrue
is applied.
The interactive tool asks you the phrase you want to send to the Google Assistant. When you types the phrase and press Enter key, the phrase is sent to the Google Assistant. After a few seconds, the response from the Google Assistant will be shown. Then, the interactive tool asks your input again.
If you want to exit from the interactive tool, press Ctrl+C
key.
Using the file
value for the -s
option, you can save each response data as a file into the directory you specify with the -o
option.
In addition, using the play
value for the -s
option, you can see each response in your Web browser in realtime.
How to Use: autopilot
Basically, in the interactive tool described at the previous section, you need to type phrases each time. Therefore, you would need to type same phrases over again and again during testing your action. This is not a productive.
The autopilot tool allows you to type phrases automatically. You can define phrases that you want to send to the Google Assistant in the YAML file named "Dialog file". The autopilot tool reads the definition file and send each phrase to the Google Assistant instead of you.
Define Dialog file
The Dialog file is written by the YAML format. The sample dialog file is the following:
locale: en-US
dialogs:
-
phrase: "Hello!"
-
phrase: "What time is it now?"
-
phrase: "Thank you."
The dialog file consists of the following items:
locale
- String. The locale string to be used on the conversation with the Google Assistant.dialogs
- Array. This has each phrase you want to send to the Google Assistant.phrase
- String. The phrase sent to the Google Assistant.
Execute autopilot
After creating the dialog file, you can start the conversation defined by the dialog file with the autopilot tool. In your terminal, execute the following command:
$ actions-tools autopilot -i dialog.yaml
The interactive tool can accept the following options:
-i
or--input
- The file path of your dialog file. Required.-c
or--credential
- The file path of the converted credential JSON file. If omitted, the<USER_HOME>/.actions-tools/credentials.json
is applied.-v
or--level
- The output level. You can specify eithersimple
anddebug
. If thesimple
selected,displayText
strings will be outputted. Otherwise, all structures that consists of the response from the Google Assistant will be outputted. If omitted, thesimple
is applied.-s
or--screen
- If you want to support the screen surface in addition to the audio, you use this option. You can specify eitheroff
,file
andplay
. If omitted, theoff
is applied.off
- Not support the screen surface.file
- Save the response data to the file in the specified directory by the-o
option.play
- Not onlyfile
, but also open the screen out data with your Web browser (Actually, the response data is passed to theopen
command. See opn).
-a
or--audio
- If you want to store and/or play the audio, you use this option. You can specify eitheroff
,file
andplay
. If omitted, theoff
is applied.off
- Do nothing.file
- Save the response data to the file in the specified directory by the-o
option.play
- Not onlyfile
, but also play the audio out data (Actually, a command you have will be used to play the MP3 file. See play-sound).
-o
or--output
- This option is required when the-s
and/or-a
option are specified and the value isfile
orplay
. You can specify the directory path where each response screen out data is written as a file. If omitted, the./
value is applied.-r
or--rich
- Turn on/off the rich output (color and emoji). If omitted, thetrue
is applied.
The autopilot tool reads the content of your dialog file and sends each phrase. You will see each response from the Google Assistant.
How to Use: test
The test tool allows you to test your actions with Mocha testing framework. You can write your test code easily using the Conversation
object, which is set up to communicate to the Google Assistant in advance.
The test tool works as a launcher of Mocha. When you write your test code with Mocha, you can execute the test code on the Mocha from the test tool. Of course, you can use other libraries to write your test code, for example Chai. To test your actions, you should need to talk to the Google Assistant from your test code. You can use the Conversation
object, which has already been configured to communicate with the Google Assistant, in your test code.
You can write and run your test code by the following step. We use actions-tools, mocha and chai to write your test code.
Prepare an environment
Here, create a directory and install dependencies.
- Create a directory to put your test code and move to the directory in your terminal.
- Link the actions-tools, which has already been installed in global, from the directory.
- Install dependencies in the directory.
$ mkdir action-test
$ cd action-test
$ npm link actions-tools
$ npm install chai
Write your test code
Write your test code with Mocha, Chai and Conversation
object. The Mocha is a testing framework based on the Behavior-Driven Development, therefore, you can write your test code with describe
and it
and etc. The Chai is an assertion library and provides should
and expect
functions. Last, the Conversation
object is provided by the actions-tools. You can retrieve the Conversation
object, which has already been configured to communicate with the Google Assistant, by the following code:
const tools = require("actions-tools");
const conv = tools.Testing.getConversation();
For example, the following code is to test the Hexadecimal conversion action.
const {expect} = require("chai");
const tools = require("actions-tools");
const conv = tools.Testing.getConversation();
describe("Happy path - Hexadecimal conversion", () => {
it("says a welcome message against starting the talk.", (done) => {
conv.say("Talk to Hexadecimal conversion").then(response => {
expect(response.displayText.length).to.equal(1);
expect(response.displayText[0]).to.include(
"Please say decimal or hexadecimal number.");
}).then(done, done);
});
it("says converted numbers against saying the number", (done) => {
conv.say("123").then(response => {
expect(response.displayText.length).to.equal(1);
expect(response.displayText[0]).to.include(
"7b hexadecimal number");
expect(response.displayText[0]).to.include(
"291 decimal number");
}).then(done, done);
});
it("ends the conversation against saying bye", (done) => {
conv.say("bye").then(response => {
expect(response.displayText.length).to.equal(1);
expect(response.displayText[0]).to.equal("See you again");
}).then(done, done);
});
});
You can send user phrases with the say
function of the Conversion
object. The say
function returns a Promise
object. You can retrieve the response as the argument of the callback function passed to the then
function. The structure of the response is the following:
displayText
- The array ofdisplayText
strings.deviceAction
- Parsed DeviceAction information.expectUserResponse
:boolean
- The boolean value of theexpectUserResponse
in AppResponse.textToSpeech
- The array oftextToSpeech
strings.ssml
- The array ofssml
strings.basicCard
- The array of Basic Card information represented by the BasicCard.carouselBrowse
- The array of Carousel Browse information represented by the CarouselBrowse.mediaResponse
- The array of Media Response information represented by the MediaResponse.tableCards
- The array of the Table Card information represented by the TableCard.suggestions
- The array of suggestion chip strings.linkOutSuggestions
- The LinkOutSuggestion information.possibleIntents
- The array of ExpectedIntent information.responseMetadata
- The response metadata information included in the DebugInfo.screenOut
- The response when supporting a screen surface. This consists of theformat
anddata
.audioOut
- The audio data formatted by MP3. This type is Uint8Array.
You need to create your test code file named *test.js
. That is, the suffix of your test code file name must be test.js
.
Execute test code
After writing your test code, you can start your test with the test tool. In your terminal, execute the following command:
$ actions-tools test -i your_action.test.js
The interactive tool can accept the following options:
-i
or--input
- The file path of your test file path. Required.-c
or--credential
- The file path of the converted credential JSON file. If omitted, the<USER_HOME>/.actions-tools/credentials.json
is applied.-l
or--locale
- The locale used during conversation with the Google Assistant. If omitted, theen-US
is applied.-r
or--report
- The report format. You can specify one of the supported reporters.
If you specify the -i
value as a directory path, all files with test.js
suffix in the directory are executed.
License
See the LICENSE file.