{"id":13799205,"url":"https://github.com/bespoken/virtual-alexa","last_synced_at":"2025-05-13T06:32:36.293Z","repository":{"id":24973173,"uuid":"102662957","full_name":"bespoken/virtual-alexa","owner":"bespoken","description":":robot: Easily test and debug Alexa skills programmatically","archived":false,"fork":false,"pushed_at":"2022-12-06T14:33:34.000Z","size":1308,"stargazers_count":112,"open_issues_count":28,"forks_count":35,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-11T18:38:34.245Z","etag":null,"topics":["alexa","alexa-custom-skill","alexa-skills-kit","alexa-voice-service","unit-testing"],"latest_commit_sha":null,"homepage":"https://bespoken.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bespoken.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-06T22:08:08.000Z","updated_at":"2024-08-22T20:33:10.000Z","dependencies_parsed_at":"2023-01-14T01:54:43.890Z","dependency_job_id":null,"html_url":"https://github.com/bespoken/virtual-alexa","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bespoken%2Fvirtual-alexa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bespoken%2Fvirtual-alexa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bespoken%2Fvirtual-alexa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bespoken%2Fvirtual-alexa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bespoken","download_url":"https://codeload.github.com/bespoken/virtual-alexa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225183827,"owners_count":17434194,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alexa","alexa-custom-skill","alexa-skills-kit","alexa-voice-service","unit-testing"],"created_at":"2024-08-04T00:00:59.820Z","updated_at":"2024-11-18T13:32:01.578Z","avatar_url":"https://github.com/bespoken.png","language":"TypeScript","funding_links":[],"categories":["SDKs/Tools"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://bespoken.io/\"\u003e\n    \u003cimg alt=\"Bespoken\" src=\"https://bespoken.io/wp-content/uploads/Bespoken-Logo-RGB-e1500333659572.png\" width=\"546\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Virtual Alexa\u003cbr\u003e\n  Interact with skills intuitively and programmatically.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://travis-ci.org/bespoken/virtual-alexa\"\u003e\n        \u003cimg alt=\"Build Status\" class=\"badge\" src=\"https://travis-ci.org/bespoken/virtual-alexa.svg?branch=master\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://codecov.io/gh/bespoken/virtual-alexa\"\u003e\n      \u003cimg src=\"https://codecov.io/gh/bespoken/virtual-alexa/branch/master/graph/badge.svg\" alt=\"Codecov\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/virtual-alexa\"\u003e\n        \u003cimg alt=\"NPM Version\" class=\"badge\" src=\"https://img.shields.io/npm/v/virtual-alexa.svg\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://bespoken.github.io/virtual-alexa/api/\"\u003e\n        \u003cimg alt=\"Docs\" class=\"badge\" src=\"https://img.shields.io/badge/docs-latest-success.svg\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://gitter.im/bespoken/bst?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge\"\u003e\n        \u003cimg alt=\"Gitter\" class=\"badge\" src=\"https://badges.gitter.im/bespoken/bst.svg\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\n# Virtual Alexa\nVirtual Alexa allows for interacting with skills programmatically.\n\nThe core Virtual Alexa API provides several routines - the three most essential ones:\n  \n    * launch: Generates JSON for a launch request\n    * intend: Generates JSON as if the given intent was uttered  \n    * utter: Generates JSON as if the user said the given phrase  \n    \nAnd also check out our YAML Test Scripts. They allow for:\n* End-to-end Testing (using our virtual devices)\n* SMAPI Simulation-Based Testing (using the Skill Management API)\n* Unit-Testing (using this library)\n\nAll via our simple, readable YAML syntax. [Read more here](https://read.bespoken.io).\n\n**What's New In The Latest Version (0.7.x)**\n* [Request Builder](https://bespoken.github.io/virtual-alexa/api/classes/skillrequest.html)\n* [Improved Dialog Manager](https://github.com/bespoken/virtual-alexa/blob/master/docs/Dialog.md)\n* More Internals - We've exposed more of the internal elements of Virtual Alexa, such as the AudioPlayer and DialogManager.\n\n## Why Do I Need This?\nThis library allows for easy testing of skills.\n\nYou can use it for:\n\n1) Unit-testing - ensuring individual routines work correctly  \n2) Regression testing - ensuring the code as a whole works properly\n\n## How Do I Get It?\n```\nnpm install virtual-alexa --save-dev\n```\n\n## How Do I Use It?\nEasy! Just add a line of code like so:\n```javascript\nconst va = require(\"virtual-alexa\");\nconst alexa = va.VirtualAlexa.Builder()\n    .handler(\"index.handler\") // Lambda function file and name\n    .interactionModelFile(\"./models/en-US.json\") // Path to interaction model file\n    .create();\n\nalexa.intend(\"PlayIntent\").then((payload) =\u003e {\n    console.log(\"OutputSpeech: \" + payload.response.outputSpeech.ssml);\n    // Prints out returned SSML, e.g., \"\u003cspeak\u003e Welcome to my Skill \u003c/speak\u003e\"\n});\n```\n\nOur \"canonical\" full example is the [Super Simple Unit Testing project](https://github.com/bespoken/super-simple-unit-testing/blob/master/test/index-test.js).\n\n### Virtual Alexa With Async/Await\nHere are some basic tests that uses async/await:\n```javascript\nit(\"Accepts responses without dollars\", async function () {\n    const alexa = bvd.VirtualAlexa.Builder()\n        .handler(\"index.handler\") // Lambda function file and name\n        .intentSchemaFile(\"./speechAssets/IntentSchema.json\") // Uses old-style intent schema\n        .sampleUtterancesFile(\"./speechAssets/SampleUtterances.txt\")\n        .create();\n\n    const launchResponse = await alexa.launch();\n    assert.include(launchResponse.response.outputSpeech.ssml, \"Welcome to guess the price\");\n\n    const playerOneResponse = await alexa.intend(\"NumberIntent\", { number: \"2\" });\n    assert.include(playerOneResponse.response.outputSpeech.ssml, \"what is your name\");\n    assert.include(playerOneResponse.response.outputSpeech.ssml, \"contestant one\");\n\n    const playerTwoResponse = await alexa.intend(\"NameIntent\", { name: \"john\" });\n    assert.include(playerTwoResponse.response.outputSpeech.ssml, \"what is your name\");\n    assert.include(playerTwoResponse.response.outputSpeech.ssml, \"Contestant 2\");\n\n    const gameStartResponse =  await alexa.intend(\"NameIntent\", { name: \"juan\" });\n    assert.include(gameStartResponse.response.outputSpeech.ssml, \"let's start the game\");\n    assert.include(gameStartResponse.response.outputSpeech.ssml, \"Guess the price\");\n\n    const priceGuessResponse = await alexa.intend(\"NumberIntent\", { number: \"200\" });\n    assert.include(priceGuessResponse.response.outputSpeech.ssml, \"the actual price was\");\n});\n```\nThis one is using Mocha (and Babel) - you can see the full example here:  \nhttps://github.com/bespoken/GuessThePrice/blob/ProgrammaticTests/test/index-test.js\n\n### Virtual Alexa With Promises\nHere's an example using promises:\n```javascript\ntest(\"Plays once\", (done) =\u003e {\n    alexa.intend(\"GetStartedIntent\").then((payload) =\u003e {\n        expect(payload.response.outputSpeech.ssml).toContain(\"What is the search term for it\");\n        return alexa.intend(\"IncorrectGuessIntent\");\n\n    }).then((payload) =\u003e {\n        expect(payload.response.outputSpeech.ssml).toContain(\"Nice try\");\n        return alexa.intend(\"IncorrectGuessIntent\");\n\n    }).then((payload) =\u003e {\n        expect(payload.response.outputSpeech.ssml).toContain(\"That is not correct\");\n        return alexa.intend(\"IncorrectGuessIntent\");\n\n    }).then((payload) =\u003e {\n        expect(payload.response.outputSpeech.ssml).toContain(\"Goodbye\");\n        done();\n\n    });\n});\n```\nYou can see the full example this is taken from here:  \nhttps://github.com/bespoken/giftionary/blob/master/test/index.test.js\n\nAnd read all the docs here:  \nhttps://bespoken.github.io/virtual-alexa/api/\n\n## Using The Request Filter\nThe [filter](https://bespoken.github.io/virtual-alexa/api/classes/virtualalexa.html#filter) is a powerful tool for manipulating the request payloads that are made to your Alexa skill.\n```javascript\nalexa.filter((requestJSON) =\u003e {\n  // Do something with the request\n  requestJSON.request.locale = \"en-US\" // Arbitrary example of changing the request payload\n});\n```\n\nMore info on using it [here](docs/Filters.md).\n\n## Using the request builder:\nOur request builder allows for fine-tuning requests with ease.\n\nTo use it, make a call to Virtual Alexa like so:\n```javascript\n// Construct the request\n\nconst request = alexa.request()\n    .intent(\"MyIntentName\")\n    .slot(\"SlotName\", \"SlotValue\")\n    .dialogState(\"COMPLETED\")\n    // Directly set any property on the JSON easily with the new set method\n    .set(\"context.System.user.permissions.consentToken\", \"\u003cTOKEN\u003e\")\n    .set(\"context.System.device.deviceId\", \"\u003cMY_DEVICE_ID\u003e\");\n\nconst response = await request.send();\n```\n\n[Read more here](https://bespoken.github.io/virtual-alexa/api/classes/skillrequest.html).\n\n## AudioPlayer Interface\nWe also support the AudioPlayer! [Read more here](https://github.com/bespoken/virtual-alexa/blob/master/docs/AudioPlayer.md).\n\n## Display Interface\nWe also support the Display Interface! [Read more here](https://github.com/bespoken/virtual-alexa/blob/master/docs/Display.md).\n\n## Dialog Interface\nWe also support the Dialog Interface. [Read more here](https://github.com/bespoken/virtual-alexa/blob/master/docs/Dialog.md).\n\nUsing our implementation, you can simulate different payloads coming from the Dialog Manager with ease.\n\n# In-Skill Purchase Responses\nYou can emulate responses from an In-Skill Purchase with the following request type:\n```\nconst request = alexa.request().inSkillPurchaseResponse(\n    \"Buy\",\n    \"ACCEPTED\",\n    \"MyProductId\",\n    \"MyToken\"\n);\n\nconst response = await request.send();\n```\n\n## Mocking External Calls (Dynamo and Address API)\nWe also support mocking external calls, such as ones made to the Address API and Dynamo.\n[Read more here](https://github.com/bespoken/virtual-alexa/blob/master/docs/Externals.md).\n\nThis allows for testing without relying on the actual calls, which are difficult if not impossible to configure for unit tests.\n\n## Entity Resolution\nWe support the entity resolution request payloads.\n\nUsing Virtual Alexa, we will automatically add entity resolution information to your slots, based on the your interaction model. It's like magic :-)\n\n[Read more here](https://github.com/bespoken/virtual-alexa/blob/master/docs/EntityResolution.md).\n\n## How Do I Talk To You?\nEasy, find us on [our Gitter](https://gitter.im/bespoken/virtual-alexa) or email [support@bespoken.io](mailto:support@bespoken.io).\n\nWe look forward to hearing from you!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbespoken%2Fvirtual-alexa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbespoken%2Fvirtual-alexa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbespoken%2Fvirtual-alexa/lists"}