Skip to content

Getting Started

Jump to bottom
Branko Juric edited this page Nov 2, 2019 · 187 revisions

Gwen logo

Get Started

System Requirements

  • Linux, Mac or Windows OS
  • Chrome, Firefox, Safari, Edge or IE web browser
  • Java JRE or JDK 8 (version 1.8) or higher
    • You can verify that you have Java installed by opening a command prompt and typing java -version. A version will be displayed if you have Java installed.
    • Install Java if you do not see a version

Install Instructions

Ensure that your system meets the above requirements and then perform the following:

Auto Updates

When you first launch Gwen, it will take a little time to download the latest version of itself before it starts executing anything. On subsequent launches it will start much faster and won't download anything again until we publish a new release in which case it will automatically update itself again.

To turn off automatic updates, open the gwen.properties file in the root gwen-workspace directory where you installed Gwen in a text editor and change the gwen.gwen-web.version property from latest to a release number of your choosing. Then save and close the file.

File: gwen-workspace/gwen.properties

# Gwen package version
# --------------------
# Gwen web version (specify desired version or latest for auto updates)
gwen.gwen-web.version=latest

Run our Samples

Gwen will want to run Chrome by default. If you do not have Chrome installed you can either install it now and continue to run the following command or skip over it to see how you can switch browsers.

If you do have Chrome installed, open a terminal (command prompt) into the gwen-workspace directory where you installed Gwen now and launch the following command to execute all the sample features located in the samples sub directory.

  • Linux/Mac/PowerShell: 
    ./gwen samples -b
  • Windows DOS: 
    gwen samples -b

The trailing -b switch tells Gwen to close the browser when execution completes.

Switch Browsers

To have Gwen run on an a browser of your choosing, just specify one of the following names as the first argument in your call to Gwen:

  • chrome : to use Chrome (default if not provided)
  • firefox : to use the Firefox
  • safari : to us Safari
  • edge : to use Edge
  • ie : to us Internet Explorer

For example, to execute all our sample features on FireFox, issue the following command in the gwen-workspace directory where you installed Gwen on your OS terminal (command prompt):

  • Linux/Mac/PowerShell: 
    ./gwen firefox samples -b
  • Windows DOS: 
    gwen firefox samples -b

The trailing -b switch tells Gwen to close the browser when execution completes.

Changing the Default Browser

If you wish to change the default browser used by Gwen from Chrome to Firefox instead (for example), open the Gwen launch script in the root of your gwen-workspace directory and change it as follows:

  • Open the script file in a text editor, change the DEFAULT_BROWSER variable from chrome to firefox and then save and close the file.

    • Linux/Mac script file: gwen-workspace/gwen

      DEFAULT_BROWSER="firefox"

    • Windows script file: gwen-workspace/gwen.bat

      SET DEFAULT_BROWSER=firefox

Gwen will now launch Firefox instead of Chrome as the default browser whenever you launch Gwen without providing an explicit browser name as the first argument. You can set any of the supported browsers mentioned above to be your default browser at any time using the method described here.

Evaluation Reports

After you execute our samples, a HTML evaluation report will be generated in the target/reports folder of your workspace. Open the index.html file in that folder in any browser to view the report. See the following links for more information about Gwen report formats and options:

Element highlighting (throttle)

You will have noticed that when Gwen executed the samples it highlighted elements on web pages in yellow as it went along locating and performing actions on them. This highlighting is controlled by the gwen.web.throttle.msecs setting in the gwen.properties file in your workspace (set to 150 msecs by default). This slows down Gwen just enough to provide you with a visual cue of what it is doing in the browser so you can observe.

You can turn this feature off by setting the throttle value to zero. If you do so, Gwen will not highlight any elements and will perform operations as fast as it can. You may want to do that when running Gwen in build server environments to optimise execution speed. You may also want to use this setting to fine tune how slow or fast Gwen performs operations depending on the performance of websites that you automate.

Recommended Reading

  1. Have a closer look at our feature and meta samples inside the samples subfolder of your Gwen workspace.

  2. Learn about how Gwen Meta can be used and get answers to some common Gwen questions.

  3. Browse through the Gwen Web DSL to get a glimpse of all the web automation capabilities and kinds of Gherkin steps that Gwen is able interpret and execute for you out of the box.

Hands On Learning

  1. Get introduced to locating web elements with Gwen:

  2. Follow the examples in the following blog articles to get practical experience with the core Gwen capabilities:

  3. After you work though all of the above, you will have a good understanding of Gwen and will be very comfortable with its command line interfaces:

Start Automating

You are now ready to start automating with Gwen. Begin by writing and saving your feature and meta files into the features sub folder of your Gwen workspace.

To execute all the features in your features folder, open a command prompt in your gwen-workspace directory and invoke Gwen as follows:

  • Linux/Mac/PowerShell: 
    ./gwen features -b
  • Windows DOS: 
    gwen features -b

If you omit the -b switch Gwen will enter the REPL mode where you can inspect the execution environment or interact with the browser where your execution ended. Type exit at the gwen> prompt at any time to exit the REPL session and return to your OS.

To execute just a single feature file, invoke Gwen on that file as follows:

  • Linux/Mac/PowerShell: 
    ./gwen features/path/to/your.feature
  • Windows DOS: 
    gwen features/path/to/your.feature -b

README.txt files are included throughout subdirectories of the workspace to help you along.

Manage Your Meta

If you're a little unsure about how to best manage your meta features, have a look at the currently available Meta strategies and use those that suit.

Inject Environment Specific Properties

You can inject environment specific properties anywhere in your meta features using the String Interpolation mechanism that Gwen provides. To configure properties for an environment, just create a new properties file in the env sub directory of your Gwen workspace and give it a name that identifies that environment.

You can inject environment properties in business features in addition to meta features, but that practice is discouraged since those features are meant to remain clean and free of any configuration. Meta features on the other hand are meant for such things.

For example, to configure dev environment properties, you would create a file named dev.properties in the env subdirectory of your workspace. There you can configure any named properties you require and reference them throughout your meta features using the ${property.name} syntax. Then to apply those properties at runtime, you can provide the name of the environment as the first argument (or second argument if you specify a browser as the first) in your call to Gwen as follows:

  • Specify the environment name as the first argument when using the default browser
    • Linux/Mac/PowerShell: 
      ./gwen dev features
    • Windows DOS: 
      gwen dev features
  • Specify the environment name as the second argument when using an explicit browser
    • Linux/Mac/PowerShell: 
      ./gwen firefox dev features
    • Windows DOS: 
      gwen firefox dev features

Tweak Gwen Settings

Gwen enables you to configure certain runtime settings to manage and change its default runtime behaviours and aspects. These settings can be configured and stored in the various properties files throughout your Gwen workspace including:

  • Global workspace properties in the gwen.properties file in the root of your workspace
  • Environment level properties files that you define in the env subdirectory of your workspace (as per the previous section)
  • Browser level properties in the browsers subdirectory of your workspace

Command Line Help

If you need help invoking Gwen, run the following command to list all options:

  • Linux/Mac/PowerShell: 
    ./gwen help
  • Windows DOS: 
    gwen help

Share Your Workspace in Git

If you want to share your work with your team or run Gwen on a build server or somewhere on the cloud, you can push your Gwen workspace to a Git repository. Be wary if changing the .gitignore file that you do not exclude the Gwen package manager (gwen-gpm.jar) which is used by the wrapper scripts to download or update Gwen where the repository is checked out.

Jira Integration

Execute automated Gwen tests for user stories, requirements or fixes directly in Jira.

User Network and Support

Join our Gwen user network to get access to news, release broadcasts, tips, discussions and support from the Gwen maintainers.

Tell Your Friends About Gwen

Tag and follow us on Twitter @gweninterpreter

Home

Clone this wiki locally