What is this?

FitNesse for Appian is a tool for Automating Appian UI tests using a combination of FitNesse and Selenium.

Overview

Selenium and FitNesse provides an "easy" way to create user interface driven automated tests with Appian. Test cases can be used for functional testing and regression testing of the user interface and the process model functional logic.

The presentation Overview of FitNese for Appian contains more information about the tool as well as a demo video.

For additional API information, view the JavaDocs.

Usage and Contributions

To use Selenium and FitNesse on your project, please follow the steps identified below for setting up the testing framework and creating/executing test cases.

We ask that whenever possible, you contribute back to the repository and the Appian PS community by

• adding any missing commands that you need to create for test cases
• fixing issues and defects
• implementing enhancements

As we work and contribute to make this tool better, we will take the greatest care to ensure that the next versions are backwards compatible. Rest assure that whatever changes are released in the future are NOT going to break your test cases.

If your team cannot directly enhance the framework, please make sure to contact the Appian CoE on Home or over email in order to provide your feedback.

We can help only if we know where the problems are!

Installation

Prerequisities

• Firefox installed
• Java JDK installed and configured
• Configure JAVA_HOME environment variable to point to your JDK installation directory.
• Add %JAVA_HOME%\bin to PATH environment variable

Installation

1. Download the newest release of AutomatedTesting.zip.
2. Unzip contents of AutomatedTesting.zip into TESTING_HOME, e.g. C:\AutomatedTesting. TESTING_HOME should not include spaces.
3. In a command prompt navigate to TESTING_HOME.
4. Run start.bat to install and run FitNesse. Installation only takes 30 seconds.

• This will also start FitNesse, to stop type ctrl+C.

NOTE: if you choose a different location for TESTING_HOME than C:\AutomatedTesting, then you must update configs/custom.properties to refer to the correct location.

Running Your First FitNesse Test

1. Start FitNesse if it isn't already running:
2. In a command prompt navigate to TESTING_HOME.
3. Run start.bat.
4. Navigate to http://localhost:8980/LoginTest.
5. Click Edit to modify test and update the following variables:

• Update the APPIAN_URL, APPIAN_LOCALE (en_US or en_GB), and APPIAN_VERSION (7.10, 7.11, or 16.1)
• Update the Username REPLACE_USERNAME and Password REPLACE_PASSWORD'

1. Click Save.
2. Click Test.

Running FitNesse Tests From Another directory

1. Open TESTING_HOME\fitnesse.properties in a text editor.
2. Update FitNesseRootDir to refer to the repository containing the FitNesseRoot folder.
3. Update FitNesseRoot to refer to the folder name containing the wikis.
4. Next time you use TESTING_HOME\start.bat the wikis will be pulled directly from the repo folders.

Setting up Jenkins with a GitHub Repo of FitNesse tests

1. Download Jenkins installer.
2. Install Jenkins.
3. Update JENKINS_HOME\jenkins.xml --httpPort argument to another port, e.g. 8081.
4. Restart Jenkins service in Window services.
5. In a browser, navigate to http://localhost:8081.
6. Add relevant plugins (FitNesse and Git):
7. Click on Manage Jenkins.
8. Click on Manage Plugins.
9. Click on Available tab.
10. Filter by FitNesse check its box and click Download now and install after restart.
11. Repeat, but filter by Git check its box and click Download now and install after restart.
12. Once restarted, set up your GitHub credentials:
13. Click on Credentials.
14. Click on Global credentials.
15. Click on Add Credentials and enter the following:
    Kind: Username with password
    Username: GitHub username
    Password: GitHub password
    Description: GitHub Credentials
16. Setup git.exe
17. Click on Manage Jenkins.
18. Click on Configure System.
19. In the Git section, populate your Path to Git executable to the location of git.exe.
20. Navigate back to the home page and click New Item.
21. Choose a build name, select Freestyle project, and click OK.
22. Setup SCM:
23. Under Source Code Management click Git.
24. Enter the Repository URL for your GitHub repository containing the fitnesse tests.
25. For Credentials select your previously enter gihub credentials.
26. Click Add build step and select Execute FitNesse test.
27. Enter the following values:
28. Select Start new FitNesse instance as part of build.
29. Enter TESTING_HOME in Java working directory.
30. Enter TESTING_HOME\lib\fitnesse-standalone.jar in Path to fitnesse.jar.
31. Enter the folder in your repository containing the FitNesse wikis in Path to FitNesseRoot, this can be subfolders.
32. Enter 8981 in Port for FitNesse instance.
33. Enter the page for the test or suite in Target Page.
34. Check Is target a suite? if the page is a suite.
35. Set HTTP Timeout and Test Timeout high enough that the tests will not timeout.
36. Enter fitnesse-results.xml in Path to fitnesse xml results file.
37. Click Add post-build action and select Publish FitNesse results report.
38. Enter fitnesse-results.xml in Path to FitNesse xml results file.
39. Click Save.
40. You can now run your FitNesse test by clicking Build Now. This will download the newest version of the FitNesse tests from the GitHub repository and run them locally.

Development Environment Setup

Setup Maven

1. Download Maven
2. Configure M2_HOME environment variable to point to your Maven installation directory.
3. Add %M2_HOME%\bin to PATH environment variable
4. Add Git to PATH environment variable

Clone the GitHub Repo

1. Clone the project repo to your local computer using git clone git@github.com:appianps/ps-ext-FitNesseForAppian.git

Eclipse Setup

1. Setup the M2_REPO variable in Eclipse by running: mvn eclipse:configure-workspace -Declipse.workspace="<your-eclipse-workspace>".

• If you don't know your eclipse workspace, open your Eclipse preferences and go to General > Startup and Shutdown > Workspaces.

1. Cleanup any existing Eclipse project files mvn eclipse:clean
2. Generate new Eclipse project files by running the following from the root of the Labs repo working directory: mvn eclipse:eclipse.
3. Open Eclipse
4. Import the projects using File > Import > General > Existing Projects into Workspace.
5. Select the repo folder and import the project.

Development

Creating a New Method

All methods that are callable in FitNesse are derived from the appian-fixture-x.x.x.jar found in C:\AutomatedTesting\lib\appian. To create or modify an existing method, you must do the following:

1. Modify class com.appiancorp.ps.automatedtest.fixture.[BaseFixture|TempoFixture] to add new methods to the corresponding environment.
2. Most methods written for these classes will simply call methods of an object in the com.appiancorp.ps.automatest.object package, e.g. verifyNewsFeedContainingTextIsNotPresent(newsText) calls TempoNews.waitFor(newsText).
3. Make sure to annotate the class for javadocs generation.
4. Add and test corresponding JUnit test cases in \src\test\java\com\appiancorp\ps\automatedtest\fixture.
5. Update the public javadocs:
6. Run Project > Generate Javadoc... and select the com.appiancorp.ps.automatedtest.fixture package (we don't need javadocs for the objects).
7. Copy the resulting docs folder onto your desktop.
8. Switch to the gh-pages branch of the repository.
9. Delete the existing docs folder in this repository and replace it with the copied version.
10. Commit and push.
11. Follow the Local build procedures below to generate a new jar for testing.
12. Copy new jar to TESTING_HOME\lib\appian\ and delete the existing version.
13. To push back to the remote repository:
    1. Create new branch for changes: git branch BRANCH_NAME then git checkout BRANCH_NAME.
    2. Publish new branch: git push.
    3. Create pull request back to master.

Building

Version Selection Methodology

• Update MAJOR version when you make incompatible API changes, e.g. removing methods, changing method names, or anything that would require updates to existing test cases.
• Update MINOR version when you add functionality in a backwards-compatible manner, e.g. adding new methods, updating drivers or jars.
• Update PATCH version when you make backwards-compatible bug fixes, e.g. fixing existing methods.

Local

1. Run mvn verify to run integration tests.
2. Run mvn clean package (add -DskipTests=true to skip unit tests).
3. Final JAR and Package are placed in the /target/ folder.

Release

A new release can be prepared by completing the following steps:

1. Run mvn release:clean.
2. Run mvn release:prepare -DpushChanges=false add -DdryRun=true to perform the Maven release procedure without commiting changes to the local repository. Add -Darguments="-DskipTests" to skip integration tests.
   This step will automatically do the following:

• Updates the pom.xml files with the release version number
• Commits the updated pom.xml files to the local git repository
• Runs all unit & integration tests and build the final packages
• Updates the pom.xml files with the next development version number
• Commits the updated pom.xml files to the local git repository

1. Push generated commits to GitHub.
2. Create new release on https://github.com/appianps/ps-ext-FitNesseForAppian/releases.

As mvn release:prepare only commits the updated pom.xml files locally, they need to be pushed to GitHub the same as any other commit. The final release JAR's are placed in the /target/ folder of each module.

Create New Installation Package

1. Checkout master branch at new tag git checkout COMMIT_HASH or TAG_NAME.
2. Run mvn package
3. Upload new package to both the GitHub release and Share Component.