Creative Web Automation: Generate User Guide with Automation Script
How to use an automated script to take screenshots and create an HTML user guide
This article shows how I use automation scripts to generate a user guide for a website. For this exercise, I will use the sign-up process on WhenWise as an example.
Why use an Automation Script?
Typically, a user guide is generally written by a technical writer after the software is complete. However, the documentation often is outdated quickly as the app evolves.
Using automated scripts to generate user guides makes document-update much easier and quicker.
A typical Online User Guide
- Navigate to the start page
- Some text to explain, followed by step by step guide.
- for each step, we might add a screenshot of the control on the page to make it clear.
For each business feature,
- Open the start page (using automation script)
- Write step description
- Take a screenshot of the controls on the page (optional)
- Combine all the above together into Markdown format
- Convert to HTML
Markdown is a popular markup language that is very readable. It is easier to use and concise, very easy to convert to HTML.
I will use WhenWise’s sign-up guide as an example.
Step 1: Open the Sign Up Page
Since this is the first step, I chose to take a full page screenshot using Selenium’s
screenshot_file = driver.save_screenshot(File.join(test_reports_dir, "step_1.png"))
After executing this,
step_1.png will be saved inside
Step 2: Fill in business name
The automation script can fill this in browser:
driver.find_element(:id, "biz_name").send_keys("Wise Business")
Because this is quite straightforward, I won’t take a screenshot in this step. In the user guide, I add the step description “Enter your business name”.
Step 3: Select business type
For this one, I need to include the business type options in the guide.
# click the dropdown
dropdown_xpath = "//select[@name='biz[business_type]']/../.."
Then locate the dropdown box (in
elem) and screenshot it.
# get only the dropdown box's content
elem = driver.find_element(:xpath, dropdown_xpath + "/ul")# screenshot the dropdown box
elem.save_screenshot (a Selenium 4 feature) only take a screenshot of the selected
step_2.png looks like:
I will add a description: “Select business type from the dropdown” to the guide.
Step 4: Enter the email and password
Similar to the business name, the automation script can fill in text-fields. Again, it is not necessary to take a screenshot in this step.
Step 5: Click the Sign Up button.
For the user guide, we can just take a screenshot of the button.
elem = driver.find_element(:id, "create-account")
step_3.png looks like:
Now, we have all the screenshots to create our user guide.
Combine all into one Markdown document
I used an array to store the step descriptions and screenshots in Markdown format in
report_md. Each array element is a new line.
# store Markdown in array
report_md = 
report_md << "## Sign up an account #123"
report_md << "1. **Open the sign up page**"
report_md << " <img src='step_1.png' height='240'/>"
report_md << "2. **Enter your business name**"
report_md << "3. **Select business type from the dropdown**"
report_md << " !(step_2.png)"
report_md << "4. **Click the 'SIGN UP' button**"
report_md << " !(step_3.png)"
For the first image,
step_1.png, I used raw HTML format to specify the height dimension. The other screenshots use standard Markdown image syntax (
Convert Markdown to HTML
I use Kramdown as the utility to convert markdown to HTML.
gem install kramdown
to_html to convert to HTML.
report_html = Kramdown::Document.new(report_md.join("\n\n")).to_html
File.open(File.join(test_reports_dir, "test-report-123.html"), "w").write(report_html)
What does it look like?
The above is raw HTML. By applying stylesheets (extending this script), it can look very professional like this one.
While this is a simple process to creating user guides, there is one thing to keep in mind. Namely, maintaining the automation scripts.
Elements can change ID/name over time
When this happens the script’s element locator might fail and won’t take screenshots correctly. Using IDs, if present, is relatively safe for changes.
If necessary, update the element locator. This is generally not a big deal if you have adopted test automation in your projects, as these will be detected during automated regression testing, in automated End-to-End functional test scripts.