Smart answers are a great tool for content designers to present complex information in a quick and simple way. Defining what they are – decision trees? calculators? tools? is immaterial – what they do is provide a reusable technical framework to build a quick and simple answer to a complex question.
Read more in a blog post.
Have a look at
test/unit/flow_test.rb for example usage.
This application supports two styles of writing and executing smart answers:
Ruby and YAML-based smart answer flows
For more information, please go to the Ruby/YAML SmartAnswer README
Smartdown-based smart answer flows
For more information, please go to the Smartdown SmartAnswer README
Switching from one style to another
Smart answers are by default expected to be in Ruby/YAML style.
To transition a smart answer from Ruby/YML to Smartdown style, register it in the smartdown registry (
Debugging current state
If you have a URL of a Smart answer and want to debug the state of it i.e. to see PhraseList keys, saved inputs, the outcome name, append
debug=1 query parameter to the URL in development mode. This will render debug information on the Smart answer page.
Visualising a flow
To see an interactive visualisation of a smart answer flow, append
/visualise to the root of a smartanswer URL e.g.
To see a static visualisation of a smart answer flow, using Graphviz:
# Download graphviz representation $ curl https://www.gov.uk/marriage-abroad/visualise.gv --silent > /tmp/marriage-abroad.gv # Use Graphviz to generate a PNG $ dot /tmp/marriage-abroad.gv -Tpng > /tmp/marriage-abroad.png # Open the PNG $ open /tmp/marriage-abroad.png
NOTE. This assumes you already have Graphviz installed. You can install it using Homebrew on a Mac (
brew install graphviz).
Installing and running
NB: this assumes you are running on the GOV.UK virtual machine, not your host.
./install # git fetch from each dependency dir and bundle install
Run using bowler on VM from cd /var/govuk/development:
Viewing a Smart Answer
To view a smart answer locally if running using bowler http://smartanswers.dev.gov.uk/register-a-birth
Run unit tests by executing the following:
bundle exec rake
If you need to add a new worldwide organisations fixture find it here by the country name or its capital city, navigate to
<found_url>.json, most likely it will be of the following format
https://www.gov.uk/api/world/organisations/british-[embassy|high-commission]-<capital city>, copy over the JSON to
test/fixtures/worldwide/<country>_organisations.json and change it to reflect the expected format based on other examples in the directory.
Testing Smartdown flows
Smartdown flows are tested using scenarios in the flow directories.
Test all Smartdown flows by running:
bundle exec ruby -Itest test/unit/smartdown_content/smartdown_scenarios_test.rb
Test a single Smartdown flow by running:
SMARTDOWN_FLOW_TO_TEST=<name-of-smartdown-flow> \ bundle exec ruby -Itest test/unit/smartdown_content/smartdown_scenarios_test.rb
Adding regression tests to Smart Answers
Generate a set of responses for the flow that you want to add regression tests to.
$ rails r script/generate-questions-and-responses-for-smart-answer.rb <name-of-smart-answer>
Commit the generated questions-and-responses.yml file (in test/data) to git.
Change the file by adding/removing and changing the responses:
Add responses for any of the TODO items in the file.
Remove responses that you don't think cause the code to follow different branches, e.g. it might be useful to remove all but one (or a small number) of countries to avoid a combinatorial explosion of input responses.
Combine responses for checkbox questions where the effect of combining them doesn't affect the number of branches of the code that are exercised.
Commit the updated questions-and-responses.yml file to git.
Generate a set of input responses and expected results for the Smart Answer.
$ rails r script/generate-responses-and-expected-results-for-smart-answer.rb <name-of-smart-answer>
Commit the generated responses-and-expected-results.yml file (in test/data) to git.
Run the regression test to generate the HTML of each outcome reached by the set of input responses.
$ TEST_COVERAGE=true ruby test/regression/smart_answers_regression_test.rb
Commit the generated outcome HTML files (in test/artefacts) to git.
Inspect the code coverage report for the Smart Answer under test (
open coverage/rcov/index.htmland find the smart answer under test).
If all the branches in the flow have been exercisde then you don't need to do anything else at this time.
If there are branches in the flow that haven't been exercised then:
Determine the responses required to exercise those branches.
Go to Step 3, add the new responses and continue through the steps up to Step 9.
Please see the github issues page.
Making bigger changes
When making bigger changes that need to be tested before they go live it is best to release them as a draft first. There is a rake task for creating a draft flow
rake version:v2[flow]. This is not ideal, but it allows to check the changes in the UI in the development and preview environments without affecting the production environment.
Once reviewed, the draft can be published by running
rake version:publish[flow]. This merges V2 changes into the original files. Take a look at the rake task to see the details. If you used any other V2 files that are not covered by the rake task, make sure to process them manually.
Commiting V2 -> V1 changes
To help developers track changes in files easily, it is best if you commit V2 files' removal in one commit, then commit the modifications to the original files. This creates an easy to browse diff of all the changes being published. Write a descriptive message for the second commit, as this is what the other developers will see in the file history.
Deploying to Heroku
The 'startup_heroku.sh' shell script will create and configure an app on Heroku, push the current branch_ and open the marriage-abroad Smart Answer in the browser.
Once deployed you'll need to use the standard
git push mechanism to deploy your changes.