User guide

    'How to' guides:

    Recording & editing:
    Recording a Walkthrough
    Recording a Walkthrough for logged in users
    Adding Step descriptions
    Moving a Walkthrough Step bubble
    Changing the Action of a Walkthrough Step
    Manually changing the Steps in a Walkthrough
    Configuring the parameters of a Walkthrough

    Playing:
    Playing Walkthroughs
    Playing a Walkthrough on a different site

    Sharing:
    Sharing Walkthroughs
    Exporting a Walkthrough

    Using Selenium to record Walkthroughs:
    WARNING: SELENIUM SUPPORT IS DEPRECATED!
    Installing Selenium IDE
    Recording Selenium tests
    Creating Walkthroughs from a Selenium test

    References:
    Supported Selenium commands
    Supported Step highlights

    Recording a Walkthrough

    The easiest way to record a Walkthrough is to use WalkHub's built-in recorder. (You have to be logged in for this.)

    1. To record a Walkthrough, click the red REC button on the top right of your screen.
    2. A pop-up is displayed. Enter the URL of the website you'd like to record your Walkthrough on.
    3. Click REC.
    4. Click through the page. The red frames show you where you can add a Walkthrough step.
    5. When you're done with recording close the Recorder window.
    6. A pop-up is displayed. Enter the title of your Walkthrough and select how much your Walkthrough changes the site it is played on. You have three options: doesn't change it, changes content or changes configuration. This setting will help warn users to only play the Walkthrough on sites where the changes won't cause any issues.
    7. Click "Save". If you decided not to save your Walkthrough and start a new recording, click "Delete, and start a new recording".

    Recording a Walkthrough for logged in users

    You have different options to create Walkthroughs for logged in users, we list them in the order of complexity:

    1. Create a Login Walkthrough: Create a Walkthrough for the login process, and set this as a prerequisite for the Walkthroughs on the admin interface. This will make sure that the user is logged in before the Walkthrough is played.
    2. Install the client: Install the client module as described here: http://walkhub.net/documentation/for-developers. Then turn off the proxy for the Walkthrough.
    3. Own WalkHub: Set up your own WalkHub and install the WalkHub client as described here: http://walkhub.net/documentation/for-developers.

    Adding Step descriptions

    After recording your Walkthrough, you can simply play it and add Step descriptions on the fly.

    1. Click "Start Walkthrough" to play the Walkthrough you recorded. The Step bubbles are automatically pre-filled with text based on the action of the Step.
    2. Click "Edit" on a Step to edit it.
    3. Add a Step description.
    4. If your Walkthrough is tour-like, add a title as well. (Optional). If you want to display Step titles, check the Show title checkbox.
    5. Click "Save", and continue editing Steps by going through your Walkthrough.

    Moving a Walkthrough Step bubble

    You can move a Step without recording the Walkthrough again.

    1. Click "Start Walkthrough" to play the Walkthrough you recorded.
    2. Click "Edit" on a Step to edit it.
    3. Click "Move" and select where you want to move this Step with the red frame.
    4. Click "Save".

    Changing the Action of a Walkthrough Step

    1. Click "Start Walkthrough" to play the Walkthrough you recorded.
    2. Click "Edit" on a Step to edit it.
    3. Click "Advanced settings".
    4. Select the action from the "Action" drop-down. See what each action does in the Supported Selenium commands section.
    5. Click "Save".

    Manually changing the Steps in a Walkthrough

    It is possible to manually add or remove Steps from a Walkthrough, and to change their order.

    1. Open the Edit form for the Walkthrough you want to change. You can do so by clicking the Edit tab for any Walkthrough you have the permissions for.
    2. Scroll down to the list of Steps.
    3. Edit the Steps:
      • To remove a Step: Click on a Step to open its Edit block and click on Remove.
      • To add a Step: Click on the "Add another item" button under the steps list. Click on the newly added Step and fill in its Edit form.
      • To move a step: Grab a Step by the double-arrow icon in front of it, and drag it to the desired position.
    4. Save the form when finished editing.

    Please play these Walktroughs on Walkthroughs you created to be able to access them.

    Configuring the parameters of a Walkthrough

    Parameters make it easy for people to reuse an existing Walkthrough. Under the "Parameters/Proxy Warning" section (by default collapsed) it is possible to manually add or remove parameters for Walkthroughs and to configure their default values.

    1. Open the edit form for the Walkthrough you want to change. You can do so by clicking the "Edit" button for any Walkthrough you have the permissions for.
    2. Click on "Parameters/Proxy Warning" to open the hidden fieldset that contains the parameters.
    3. Edit the parameters: For parameters to be recognised, you have to add the parameter name in square brackets while recording the Selenium steps, for example: [name], then add the parameter name on the Walkthrough edit form without the square brackets, for example: name.
      • To remove a parameter: Click the remove button under the parameter.
      • To add a parameter: Click on the "Add another item" button under the parameter list.
    4. Enter your preferred default value for the parameters.
    5. Save the form when finished editing.

    Tips

    • You can use parameters for any arbitrary variable information you want to insert into your Walkthrough.
    • You can use parameters in the share url functionality to pass information about a user to WalkHub (e.g. name, information you want to automatically add to their form submission, etc.)

    Please play this Walktrough on a Walkthrough you created to be able to access it.

    Playing Walkthroughs

    Walkthroughs are stored and played from a WalkHub (this could be WalkHub.net, your own dedicated WalkHub or your Drupal site on which you have enabled the WalkHub module).

    1. Open the Walkthrough you want to run.
    2. Click on the "Start Walkthrough" link to open the "Start Walkthrough dialogue".
    3. Review the Walkthrough parameters in the dialogue and if necessary replace their default values.
    4. Click on the "Start Walkthrough" link in the dialogue
    5. The Walkthrough will open.
    6. At any time you can click the [x] at the top right of the window to close the Walkthrough and to return to the Walkthrough page.

    Playing a Walkthrough on a different site

    You can play the same Walkthrough on different sites as long as they have the same structure.

    1. Click on the "Start Walkthrough" link to open the "Start Walkthrough dialogue".
    2. Change the URL in the Domain field to the site you want to play the Walkthrough on.
    3. When you click the "Start Walkthrough" button, the Walkthrough will be played on the site you specified.

    Sharing Walkthroughs

    WalkHub makes it easy to create hyperlinks that will launch a Walkthrough with your preferred parameters already pre-filled in the launch dialogue.

    1. Open the Walkthrough you want to share.
    2. Click on the "Start Walkthrough" link to open the "Start Walkthrough dialogue".
    3. Review the Walkthrough parameters in the dialogue and if necessary replace their default values.
    4. In the "Share with these parameters" text area, the parameters in the share URL will automatically be changed to match the values you change.
    5. Copy the URL in the "Share with these parameters" text area.

    You can also share a Walkthrough by playing it to the end and clicking the corresponding buttons to share it

    • on Twitter
    • on Facebook
    • on Google+
    • in email

    Exporting a Walkthrough

    You can export a Walkthrough to PHPUnit or Selenium.

    Exporting to PHPUnit:

    1. Click "Export to phpunit" on any Walkthrough you have the permissions for.
    2. The code will appear in a new window where you can copy it.

    Exporting to Selenium:

    1. Click "Export to Selenium" on any Walkthrough you have the permissions for.
    2. A save dialog window will appear where you can download the Selenium source code in html format, that you can import to Selenium IDE (copy the html file source and paste into the Selenium source).

    Installing Selenium IDE

    Selenium IDE is a Firefox plugin that can record and playback interactions with a browser. WalkHub can turn Selenium tests into Walkthroughs.

    1. Using Firefox, first, download the IDE from the SeleniumHQ downloads page.
    2. Firefox will protect you from installing add-ons from unfamiliar locations, so you will need to click ‘Allow’ to proceed with the installation.
    3. Select Install Now. The Firefox Add-ons window pops up, first showing a progress bar, and when the download is complete, asks you to restart Firefox.
    4. Restart Firefox.
    5. To run the Selenium-IDE, simply select it from the Firefox Tools menu. It opens with an empty script-editing window and a menu for loading, or creating new test cases.

    Selenium IDE only exists as a Firefox plugin, you can install Firefox from its website.

    If you need a more thorough explanation, follow the steps here to install Selenium IDE for your browser.

    Recording Selenium tests

    To create a Selenium test you can simply record your interactions with a website using a tool like Selenium IDE.

    1. In Firefox open Selenium IDE under the Tools menu item
    2. Create a new test case (Right click on the test case list and select "New Test Case")
    3. Make sure the record button is turned ON
    4. Type the URL where you want to record the interaction sequence for your Walkthrough.
    5. Perform the actions you want your Walkthrough users to perform with example data. Selenium-IDE will automatically insert commands into your test case based on your actions.
    6. Copy the source of the test case you have just created to your clipboard. You will later paste this into the "Create from Selenium test" field on the walkthrough creation form.
    7. Optionally you can store your test case as an HTML file in Selenium IDE.

    Important

    • Don't skip the 3rd step, even if you are already on the right page, else the Walkthrough you generate won't work!
    • Don't use confidential data like usernames and passwords, unless you are planning to share them with anyone who will be playing your Walkthrough.

    Creating Walkthroughs from a Selenium test

    Walkthroughs are created as content on a WalkHub. You can use a Selenium test to automatically create steps and example actions for your Walkthrough.

    1. Log in to Walkhub.net
    2. Open the Import Walkthrough form. On WalkHub.net you can find it under the "Add content" menu.
    3. Paste the source of a Selenium test (recommended). You should have copied it to your clipboard in the Recording Selenium Tests Task.
    4. Give your Walkthrough a name (required).
    5. Add a description (recommended).
    6. Click save to save the Walkthrough.
    7. After saving the walkthrough, click on the "Start Walkthrough" link (first on the Walkthrough page and a second time on the Start Walkthrough dialogue) to verify if your Selenium test was imported correctly.
    8. For each step click on the Edit button and replace the automatically generated title with a title of the Step if needed. Otherwise only add a description.

    Supported Selenium commands

    WalkHub currently only supports the most common Selenium commands. You can use them to trigger an automatic action when a user clicks the next button on a Walkthrough Step.

    Step without commands

    It is possible to create a step that does not contain any commands. In this case the Walkthrough will display the Step on the element indicated in the "Step highlight" field but it won't perform any actions when the "next" button is clicked.

    Open

    Example Step Selenium commands:

    • Command 1: open
    • Command 2: http://[domain]
    • Command 3:

    Every Walkthrough needs to start with a step with an open command, else a Walkthrough will not start. Notice that command 2 contains a domain parameter, that will be replaced with it's default value or another value selected by the Walkthrough user.

    Click

    Example Step Selenium commands:

    • Command 1: click
    • Command 2: link=Show Advanced settings
    • Command 3:

    This command is also used to toggle checkboxes and radio buttons.

    ClickAndWait

    Example Step Selenium commands:

    • Command 1: ClickAndWait
    • Command 2: link=Walkthrough
    • Command 3:

    This command is used when the browser needs to load a new page after a link/button is clicked.

    Type

    Example Step Selenium commands:

    • Command 1: Type
    • Command 2: id=edit-body-und-0-value
    • Command 3: A walkthrough that creates a walkthrough that creates walkthroughs

    Select

    example Step Selenium commands:

    • Command 1: select
    • Command 2: id=edit-timezone--2
    • Command 3: label=Australia/Melbourne: Wednesday, August 7, 2013 - 07:41 +1000

    Supported Step highlights

    WalkHub uses the Selenium selector naming conventions to define on what element the Step dialogue will be shown on.

    Steps without "Step highlight"

    The "open" Step at the beginning of a Walkthrough does not contain a Step highlight. Instead the Walkthrough executes the open command automatically and does not wait for user feedback.

    link=

    Link is used to identify hyperlinks. This is a very commonly used selector strategy in Selenium with the disadvantage that the Walkthrough will look for the first instance of a link that contains the link title and click that link. This is a known issue and we are working on a solution to make this more robust.

    Example Step highlight: link=Walkthrough

    id=

    id is used to identify an element with a specified CSS id. This is commonly used for the type Selenium command.

    Example Step highlight: id=edit-title

    xpath=

    When Selenium IDE can't uniquely identify an element with any of it's other selector strategies, it creates an xpath selector. This is often not very robust.

    Example Step highlight: xpath=(//button[@type='button'])[3]