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

1. Navigate to the start page
2. Some text to explain, followed by step by step guide.
3. for each step, we might add a screenshot of the control on the page to make it clear.

Automation Design

For each business feature,

1. Open the start page (using automation script)
2. Write step description
3. Take a screenshot of the controls on the page (optional)
4. Combine all the above together into Markdown format
5. Convert to HTML

Why Markdown?
Markdown is a popular markup language that is very readable. It is easier to use and concise, very easy to convert to HTML.

Implementation

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 driver.save_screenshot.

driver.get("https://whenwise.agileway.net/become-partner")
screenshot_file = driver.save_screenshot(File.join(test_reports_dir, "step_1.png"))

After executing this, step_1.png will be saved inside /tmp (test_reports_dir):

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.

Before screenshotting the drop-down box, click the box and wait for the options to appear (wait is necessary for the Javascript).

# click the dropdown
dropdown_xpath = "//select[@name='biz[business_type]']/../.."
driver.find_element(:xpath, dropdown_xpath).click
sleep 0.2 # wait for JavaScript

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(File.join(test_reports_dir, "step_2.png"))

elem.save_screenshot (a Selenium 4 feature) only take a screenshot of the selected elem. So 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")
elem.save_screenshot(File.join(test_reports_dir, "step_3.png"))

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

Use kramdown’s to_html to convert to HTML.

require "kramdown"
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?

Add Styling

The above is raw HTML. By applying stylesheets (extending this script), it can look very professional like this one.

Considerations

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.