Blog

Setup Appium on OSX

Background

Appium is an open source test automation framework for use with native, hybrid and mobile web apps. It drives iOS, Android, and Windows apps using the WebDriver protocol.
– http://appium.io

Prerequisites

  • Xcode updated to latest version (through the App Store)
  • Simulator started or a physical device plugged into your Mac via USB
  • Java SDK installed and JAVA_HOME path set

Run the following commands, in Terminal, to install the necessary packages:

  1. homebrew
    • /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  2. npm
    • $ brew install node
  3. appium
    • $ npm i -g appium
  4. libimobliedevice
    • $ brew install libimobiledevice
  5. ios-deploy
    • $ npm install -g ios-deploy
  6. (Optional) appium-repl
    • $ npm install appium-repl -g
  7. Xcode command line tools
    • xcode-select --install
  8. Carthage
    • $ brew install carthage

Getting and Installing Appium

  1. In your web browser, navigate to https://github.com/appium/appium-desktop/releases/latest
  2. Download appium-desktop-#.#.#.dmg
  3. Open the .dmg file
  4. Drag the Appium icon to your Applications folder
    • Once complete, close the dmg’s window and delete the .dmg file
  5. Start Appium
    • (If prompted) Select “Open”
    • (Optional) Right-click the Appium icon in the dock and then select “Options” → “Keep in Dock”
  6. Click the “Start Server v#.#.#” button
  7. Click “⏸” (Stop Server) button
  8. Close the window to exit Appium Desktop

Start Inspector Session Using Xcode’s iOS Simulator

  1. Open XCode
  2. Select “Xcode” → “Open Developer Tool” → “Simulator”
    1. (Optional) Right-click the Simulator icon in the dock and then select “Options” → “Keep in Dock”
  3. Select “Hardware” → “Device” → “Manage Devices…”
    • Keep this window up for later
  4. Open Appium Desktop
  5. Click the “Start Server v#.#.#” button
  6. Click the “🔍” (Start Inspector Session) button
  7. Enter the following Desired Capabilities
    • automationName : XCUITest
    • platformName : iOS
    • deviceName : iPhone Simulator
    • app : {path_to_app}
  8. (Optional) Save the “Capability Set” by clicking the “Save” button
  9. Click the “Start Session” button
    • Note: The Simulator will close and a new “Appium” Simulator will be launched

Start Inspector Session Using a Physical iOS Device

The process is the same as with the Simulator, with two exceptions:

  1. Desired Capability – “app”
    • Should point to an “.ipa” instead of a “.app”
  2. Desired Capability – “deviceName”
    • Should match the Name under “Xcode” → “Window” → “Devices”

Selenium Selector Cheat Sheet

Background

Selenium uses the By class to find elements on a page. There are a number of tools to help you find a selector but once you figure out how they work you should be able to figure it out using just the element’s HTML. Creating a selector that is reliable enough to find your element, no matter its position on the page, is a learned skill. It is highly recommeded that you review the documentation for CSS Selectors and XPath Syntax.

Selenium Selector Cheat Sheet

The following tables focus on FindElement (and not FindElements), so any JavaScript function that returns multiple results is directed to return only the first (at index 0).

Basic Selenium Selectors

Description Selenium Selector JavaScript Selector
By.ByClassName  By.ClassName(“gsfi”)  document.getElementsByClassName(“gsfi”)[0]
By.ByCssSelector By.CssSelector(“#hplogo”) document.querySelector(“#hplogo”)
By.ById By.Id(“hplogo”) document.getElementById(“hplogo”)
By.ByLinkText  By.LinkText(“About”)  $x(“//a[text()=’About’]”)
By.ByName  By.Name(“q”)  document.getElementsByName(“q”)[0]
By.ByTagName  By.TagName(“a”)  document.getElementsByTagName(“input”)[0]
By.ByXPath By.XPath(“//*[@id=’hplogo’]”) $x(“//*[@id=’hplogo’]”)
  • All XPath expressions can be evaluated using jQuery. jQuery commands typically start with $
  • In XPath * is a wildcard. “//*[…” says to find any element type. “//a[…” says to find only <a> element types.

Advanced Selenium Selectors

Description Selenium Selector JavaScript Selector
Parent Element  childElement.FindElement(By.XPath(“..”)) childElement.parentElement
Element Containing Text  By.XPath(“//*[text()[contains(.,’Privacy’)]]”)  $x(“//*[text()[contains(.,’Privacy’)]]”)[0]
 Element Attribute By.CssSelector(“input[value=’3.2′]”)  document.querySelector(“input[value=’3.2′]”)
 Element Attribute By.XPath(“//input[@value=’3.2′]”)  $x(“//input[@value=’3.2′]”)

Selector Tips

Long Selectors

Using Chrome (covered below), I got a selector for Google’s “Google Search” button: #tsf > div.tsf-p > div.jsb > center > input[type="submit"]:nth-child(1). This selector reads, “Get the element with ID=’tsf’, then its child div with class=’tsf-p’, then its child div with class=’jsb’, then its child ‘center’ element > then its child input with type=’button’ and is the first child”. This selector can be trimmed down to any of the following:

  1. “center > input”
    • Returns the first <center> element’s first <input>
    • Brittle warning: If the element is moved, <center> element is removed, or another <input> becomes the first child.
  2. “input[type=submit]”
    • Returns an<input> element where type=”submit”
  3. “//*[@value=’Google Search’]”
    • Returns any element where value=”Google Search”
    • Brittle warning: If another element has the same value and appears first in the document.

Dynamic Attributes

Lets say we have a selector, “#div123 > a” and the “div123″ is dynamically generated and changes every time the page is reloaded. One simple trick is to edit the element and remove the id=”” attribute. This is done by inspecting the element and then double clicking the id attribute. When you get a new selector, it will have gone up the document tree a bit and might now look like “section > div > a” where ‘div” was the dynamically ID’d element.

 

Multiple Child Elements

This can be related to dynamic classes, too. A <ul> might have 5 <li> children. When the <ul> is first presented, all the <li> have the same class. Once one is selected the class of the selected element changes. For this example, let’s say that it goes from “li.defaultState” to “li.selected”. If your selector is “ul > li.defaultState:nth-child(5)” (to select the last <li>) you would receive an error since now only 4 elements have that class. This selector can be modified to the following:

  1. “ul > li:nth-child(5)”
    • Returns the 5th <li> of the first <ul>
    • Brittle warning: If the <ul> child count changes or if another <ul> appears first in the document.
  2. “//li[text()=’Coffee’]”
    • Returns the first <li> found where the textContent=”Coffee”
    • Brittle warning: If another <ll> appears first in the document with the same textContent value.

Getting a Selector Using Chrome’s DevTools

  1. Navigate to https://www.google.com/
  2. Right-click on the logo and then select “Inspect”
  3. The element is highlighted in the “Elements” tab of Chrome’s DevTools
  4. Right-click on the highlighted element and then select “Copy → Copy selector”

Testing a Selector Using Chrome’s DevTools Element Search

  1. Open Chrome’s DevTools [F12] and then select the “Elements” tab
  2. Press [Ctrl]+[F] to open the search
  3. Paste in your selector and if the element is found, then it will be highlighted

Testing a Selector Using JavaScript

  1. Open Chrome’s DevTools [F12] and then select the “Console” tab
  2. In the command line type document.querySelector("#hplogo") and then press [Enter]
  3. Hover over the returned element and the element will be highlighted on the page

Selenium Selectors and JavaScript

As seen in the previous section, you can test CSS Selectors using plain ol’ JavaScript. The document object is the deserialized HTML. We then call a method of that object. This can be querySelector (returns the first element matching the expression) or querySelectorAll (returns all elements matching the expression). These methods match Selenium’s functionality:

document.querySelector("your-selector-here") → driver.FindElement(By.CssSelector("your-selector-here"))

document.querySelectorAll("your-selector-here") → driver.FindElements(By.CssSelector("your-selector-here"))

Change Sticky Notes Font

Background

Sticky Notes has shipped with Windows since Windows 7 and I use it everyday. My gripe is the default font that is used in Segoe.

Change Sticky Notes Font

  1. Open the Start Menu
  2. Type regedit and then press [Enter]
  3. Drill down the file tree (in the left-hand pane) to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts
  4. In the right-hand pane, select the entry for “Segoe Print (TrueType)”
  5. Right-click that entry and select “Modify…”
  6. Change the value from segoesc.ttf to segoeui.ttf
  7. In the righ-hand pane, select the entry for “Segoe Print Bold (TrueType)”
  8. Right-click that entry and select “Modify…”
  9. Change the value of segoescb.ttf to segoeuib.ttf
  10. Reboot

Configure Windows 10 and Edge for Selenium Grid

Background

I ran into an issue while using the Microsoft WebDriver (for Edge) where if there was no RDP session, then the tests would fail and throw an exception that Selenium couldn’t get the window handle after opening the browser. Official issue ticket logged here.

Solution

Credit goes to Olena F. from the same issue ticket linked above.

  1. RDP into your Grid Node
  2. Open cmd
  3. Type qwinsta and press [Enter]
  4. Get the ID of the current RDP process
  5. Create a .bat file with the following content: %windir%\system32\tscon.exe # /dest:console
    • Replace # with the ID from step 4
  6. On the desktop, create a shortcut to you .bat file
  7. Right-click on the shortcut and select “Properties”
  8. Select “Advanced…”
  9. Select “Run as administrator”
  10. Select “OK” to close the Advanced options window
  11. Select “OK” to close the Properties window
  12. Double-click the shortcut
    • You will be kicked of the machine if it works

Note: The script to start the node (covered in this post) will need to be ran while you have control of the RDP session.

The State of Selenium 3 WebDrivers

Background on Selenium 3 WebDrivers

… all the major browser vendors ship their own implementations (Apple, Google, Microsoft, and Mozilla).
… there is now a W3C specification for browser automation, based on the Open Source WebDriver. This has yet to reach “recommendation” status, but the people working on it (including members of the Selenium project!) are now focusing on finishing the text and writing the implementations.
– https://seleniumhq.wordpress.com/2016/10/13/selenium-3-0-out-now/

The Issue

While official support from browser vendors and an accompanying W3C spec are a step in the right direction, we are in the midst of a transition phase. The spec is still in “working” status. So any vague specs are either implemented as the browser vendor sees fit or not at all.

Examples

Mozilla and “Actions”

So the deal is that “actions” is terribly underspecified. I have been trying to fix that, but it’s very unclear to me what the semantics are supposed to be (e.g. when you move the mouse, should events be dispatched on all the elements along the pointers’ path). Until that is clear it’s not going to be possible to make this work the same way across multiple implementations.
– https://github.com/SeleniumHQ/selenium/issues/2285#issuecomment-227742441

Track the status of the implementation:

Apple and “Wait”

I haven’t found a bug tracker for this issue but the (above) screenshot shows that “Wait” is not implemented in Safari. This test runs fine on all the other browsers you see in the screenshot.

Workarounds

Until such time as the WebDrivers are fully fleshed out and implemented you’ll have to craft your own code if you want to test in all browsers. I do what I can in JavaScript using the JavascriptExecutor.

The Method:

The Usage:

 Non-Selenium 3 Specific Issue – IE .Click()

The IE WebDriver is still packaged with the Selenium download [Source] and to my knowledge not made by Microsoft (their efforts seem focused on Edge at this time). The .Click() implementation has mixed results [Source]. So I use JavaScript’s .click() instead.

Working with Selenium 3 Grid

Selenium 3 Grid

Selenium-Grid allows you run your tests on different machines against different browsers in parallel. That is, running multiple tests at the same time against different machines running different browsers and operating systems. Essentially, Selenium-Grid support distributed test execution. It allows for running your tests in a distributed test execution environment.
http://www.seleniumhq.org/docs/07_selenium_grid.jsp#what-is-selenium-grid

Getting the Necessary Files

This post will cover a Selenium 3 Grid setup with a Windows hub and an OSX Safari node. I highly recommend having a readme.txt file to each folder so that you can record the version number and URL for each file. If you change the file names you are going to have a bad time.

Windows

For your convenience I have uploaded a .zip of the necessary files for Windows. Download Link: Selenium_Windows.zip

Download the following files and place them in C:\Selenium

Set Your Path File

  1. Right-click “This PC” and select “Properties”
  2. In the left navigation menu, select “Advanced system settings”
  3. Select the “Advanced” tab
  4. Select “Environment Variables…”
  5. Under “System variables” select “Path” and then select “Edit…”
  6. Select “New”
  7. Enter C:\Selenium\
  8. Select “OK”

OSX

Download the following files and place them in ~/Documents/Selenium

Enable Automation Playback in Safari

  1. Ensure that the Develop menu is available.
    • It can be turned on by opening Safari preferences (Safari > Preferences in the menu bar), going to the Advanced tab, and ensuring that the Show Develop menu in menu bar checkbox is checked.
  2. Enable Remote Automation in the Develop menu.
    • This is toggled via Develop > Allow Remote Automation in the menu bar.
  3. Authorize safaridriver to launch the webdriverd service which hosts the local web server.
    • To permit this, run /usr/bin/safaridriver once manually and complete the authentication prompt.

Creating the Necessary Scripts

Windows – Start Grid Hub

Create a new file called start-grid-hub.bat and paste in the following:

cd C:\Selenium
java -jar selenium-server-standalone-3.3.1.jar -role hub

Note: Be sure to replace 3.3.1 with the current version number.

Windows – Start Grid Node

Create a new file called start-grid-node.bat and paste in the following:

cd C:\Selenium
java -Dwebdriver.chrome.driver=C:\Selenium\chromedriver.exe -Dwebdriver.gecko.driver=C:\Selenium\geckodriver.exe -Dwebdriver.edge.driver=C:\Selenium\MicrosoftWebDriver.exe -jar selenium-server-standalone-3.3.1.jar -role node -hub http://localhost:4444/grid/register

Note: Be sure to replace 3.3.1 with the current version number and localhost with your hub’s machine name or IP.

OSX – Start Grid Node

Create a new file called start-grid-node.sh and paste in the following:

#!/bin/bash
cd ~/Documents/Selenium/
java -jar selenium-server-standalone-3.3.1.jar -browser browserName=safari,platform=MAC -role node -hub http://localhost:4444/grid/register

Note: Be sure to replace 3.3.1 with the current version number and localhost with your hub’s machine name or IP.

WebDriver Setup

To create a driver that uses the remote instance of Safari add the following to your code:

DesiredCapabilities capabilities = DesiredCapabilities.Safari();
capabilities.SetCapability(CapabilityType.BrowserName, "safari");
capabilities.SetCapability(CapabilityType.Platform, "MAC");
driver = new RemoteWebDriver(hubUri, capabilities);

Note: The code (above) is C# so you may have to massage it a bit to work in other languages.

Running the Test

  1. On the Windows machine, run start-grid-hub.bat
  2. On the OSX machine:
    1. Open Terminal
    2. Drag-and-drop the start-grid-node.sh file into the Terminal window and then press [Enter]
  3. On the Windows machine, run your test(s)

Fix webdriver.chrome.driver system property Error

Background – webdriver.chrome.driver system property

I was following along Selenium’s quick-start guide but kept getting an error, “The path to the driver executable must be set by the webdriver.chrome.driver system property“. Most of the answers I found were for Java and simply set the value in code. I tried a similar fix in C# to no avail. Finally, I found a solution that works that sets the values as command-line parameters when I launch the Node.

Files

All files were placed in C:\Selenium. An entry was added to my Windows PATH variable by:

  1. Right-click “This PC” and select “Properties”
  2. In the left navigation menu, select “Advanced system settings”
  3. Select the “Advanced” tab
  4. Select “Environment Variables…”
  5. Under “System variables” select “Path” and then select “Edit…”
  6. Select “New”
  7. Enter C:\Selenium\
  8. Select “OK”

Start the Hub

The following script will start the Grid Hub (on the default port of 4444).

cd C:\Selenium
java -jar selenium-server-standalone-3.0.0.jar -role hub

Start the Node

The following script will start a Grid Node (on the default port of 5555). It will also register the locations of the Chrome and Firefox WebDrivers (respectively).

cd C:\Selenium
java -Dwebdriver.chrome.driver=C:\Selenium\chromedriver.exe -Dwebdriver.gecko.driver=C:\Selenium\geckodriver.exe -jar selenium-server-standalone-3.0.0.jar -role node -hub http://localhost:4444/grid/register

Automated API Testing Using Powershell

Background

About a year ago I was worked on a project where we had to write a RESTful API from the ground up in Node. After the first few controllers, manual testing become quite tedious and labor intensive. One of the biggest rules in SQA is “automate what you can”. So, once we had a few endpoints solidified to match the RESTful pattern, I got to work. It took about 8 hours to come up with this automated testing solution and it saved countless hours of manual QA and tickets bouncing back-and-forth between QA and DEV (because they didn’t have unit tests). I put the solution on a VM that anyone working on the project could access, modify, and run. Let’s get started with API Testing Using Powershell.

Why Powershell?

I wanted to use the HttpClient from .Net 4.5 that I used in a lot of previous projects. The devs I was working with were MEAN and LAMP stack proficient, so I had to be sure to “Keep It Stupid Simple” and be sure to comment.

The Setup

As previously mentioned, I use the HttpClient (System.Net.Http.dll). I also import the JSON.Net (Newtonsoft.Json.dll) library to parse the JSON response from the RESTful API. In the project you’ll also see a .CSV file (check it out on GitHub). The CSV file is what makes this a data-driven testing solution that is easily updated and read by both machine and man.

The Code

You can view/fork the code from my GitHub project. You’ll need Powershell to run it, but I highly recommend using Powershell ISE. I am not going to copy+paste the code like in my other posts but rather I will explain it at a high-level.

What’s Going On

  1. Get the Present Working Directory (pwd) and save it for the next few steps
  2. Import the .dll files (see “The Setup” above)
  3. Set the BaseUrl, so that only the endpoints need to be specified in the .CSV file
    • This allows you to easily switch environments
  4. Create a new instance of the HttpClient
    • This will hold your session, so that you can log-in with one test and then do some call that requires a valid session afterwards
  5. Import the .CSV file
  6. Parse the .CSV file using a foreach loop
    1. Create an error array
    2. Create a description of the current test (row of the .CSV)
    3. Build a request with the given data
      • If the Method is PUT or POST, then add the body content
    4. Send the request and save the response
    5. Save the response’s status code
    6. Save the response’s content
    7. If the expected status code does not match the response’s, then we add that error message to the error array
    8. If the error array has any length, then we print out an error (with red text-color)
      • Else, print out a success message (with green-text)
    9. If there is a comment in the .CSV file’s current row, then print that out (with gray-text)

API Testing Using Powershell in Action

API Testing Using Powershell Screenshot

Using the JIRA API via Chrome App

Background

I started making a JIRA plugin (in JAVA) and was bothered by the all the fluff that was needed and terrible documentation from Atlassian. All I really needed was to call the JIRA API and handle the JSON data returned. So, I whipped up a Chrome App in a couple hours.

Bootstrap and jQuery

Typically I avoid these if at all possible. Not because they aren’t great or anything, but because I consider them ‘shortcuts’ and find more value in doing everything by hand. In a previous project, getting rid of jQuery cut my package size in half. For this project, I decided to use both in the interest in pumping out a Proof of Concept as fast as possible.

The Source Code

This project is hosted on GitHub. Pull down the package and load in Chrome by enabling developer options and loading the unpacked package. Alternatively, use this Chrome App to load the App.

Calling the JIRA API

The user is shown a login page. The user enters the JIRA URL, like https://example-jira.atlassian.net/, and their username and password (note this will not work if you only use oAuth to login). When the user submits the form I make an AJAX call to the endpoint rest/auth/latest/session using Basic Auth. If the login is successful a dummy dashboard is shown, else an error message is display on the login form.

Screenshot

JIRA API

Making a JIRA Plugin

Background

I wanted to make a plugin for Atlassian’s JIRA platform that can be used on the cloud based solution. This walk-through will cover the necessary steps to get going and create a JIRA Plugin that will be it’s own page. I will cover getting the SDK, setting up Eclipse, and adding a new page to JIRA. This turned out to be more painful than it should have been thanks to confusing and outdated documentation.

Setup

This post will cover development in OSX (El Capitan more specifically). If you are a Windows user, check out the official documentation.

Verify the Java Developer Kit (JDK) is Installed

  1. Open Terminal
    Screen Shot 2016-05-05 at 1.44.40 PM
  2. Enter: javac -version
    Screen Shot 2016-05-05 at 1.45.45 PM

    • If Java is installed, then move onto the next section.
  3. If you see the following prompt select “OK” (if you select “More Info…” your default browser will open a link to Oracle.com
    Screen Shot 2016-05-05 at 1.48.38 PM
  4. In your browser, navigate to the JDK8 downloads page
    Screen Shot 2016-05-05 at 1.50.41 PM
  5. Scroll down to the first section titled, “Java SE Development Kit…”
    Screen Shot 2016-05-05 at 1.51.43 PM
  6. Select the radio button, “Accept License Agreement”
    Screen Shot 2016-05-05 at 1.53.13 PM
  7. Select the proper download for your system
    Screen Shot 2016-05-05 at 1.54.58 PM
  8. Run the .dmg file from your Downloads folder
    Screen Shot 2016-05-05 at 1.57.47 PM
  9. Double-click on the box icon to begin the installation
    Screen Shot 2016-05-05 at 1.58.42 PM
  10. Select “Continue”
    Screen Shot 2016-05-05 at 1.59.42 PM
  11. Select “Install”
    Screen Shot 2016-05-05 at 2.00.39 PM
  12. Enter your password and select “Install Software” to continue
    Screen Shot 2016-05-05 at 2.01.49 PM
  13. After the install completes, select “Close”
    Screen Shot 2016-05-05 at 2.03.18 PM
  14. Close the JDK installer window
    Screen Shot 2016-05-05 at 2.04.41 PM
  15. Right-click on the installer on your desktop and select, “Eject…”
    Screen Shot 2016-05-05 at 2.06.07 PM
  16. Delete the .dmg file from your Downloads
    Screen Shot 2016-05-05 at 2.08.03 PM
  17. In Terminal, enter javac -version
    Screen Shot 2016-05-05 at 2.11.23 PM

    • If your system can not locate Java, then you may need to set your PATH

Install the Atlassian SDK

  1. In your browser, download the PKG file
    Screen Shot 2016-05-05 at 2.19.48 PM
  2. Run the .dmg file from your Downloads folder
    Screen Shot 2016-05-05 at 2.41.51 PM
  3. Double-click the icon to begin the installation
    Screen Shot 2016-05-05 at 2.42.36 PM
  4. Select the “Open” button in the alert
    Screen Shot 2016-05-05 at 2.43.26 PM
  5. Enter your password and select “OK”Screen Shot 2016-05-05 at 2.44.37 PM
  6. Select “Next >”
    Screen Shot 2016-05-05 at 2.46.09 PM
  7. Select “Next >”
    Screen Shot 2016-05-05 at 2.46.41 PM
  8. After the install completes, select “Finish”
    Screen Shot 2016-05-05 at 2.48.18 PM
  9. Close the installer window
    Screen Shot 2016-05-05 at 2.48.54 PM
  10. Right-click on the installer on your desktop and select, “Eject…”
    Screen Shot 2016-05-05 at 2.50.26 PM
  11. Delete the .dmg file from your Downloads
    Screen Shot 2016-05-05 at 2.51.37 PM
  12. In Terminal, enter atlas-version
    Screen Shot 2016-05-05 at 2.53.10 PM

Running JIRA Locally

  1. In Terminal, enter mkdir tutorial
    Screen Shot 2016-05-05 at 4.03.55 PM
  2. Enter cd tutorial
    Screen Shot 2016-05-05 at 4.05.04 PM
  3. Enter atlas-run-standalone --product jira
    Screen Shot 2016-05-05 at 4.25.53 PM

    • You will be asked to join the developer mailing list, just enter n so the process can continue unimpeded
  4. In your browser, open the URL displayed in Terminal
    Screen Shot 2016-05-05 at 4.30.25 PM
  5. Login using admin for both the Username and Password
    Screen Shot 2016-05-05 at 4.44.32 PM
  6. Select “Continue”
    Screen Shot 2016-05-05 at 4.34.10 PM
  7. Select “Next”
    Screen Shot 2016-05-05 at 4.35.45 PM
  8. Select “Skip quick tour”
    Screen Shot 2016-05-05 at 4.36.33 PM
  9. Enter Test Project for the Project name and TEST for the Key, and then select “Create Project”
    Screen Shot 2016-05-05 at 4.38.06 PM
  10. Select “Skip”
    Screen Shot 2016-05-05 at 4.39.30 PM
  11. Close your browser
    Screen Shot 2016-05-05 at 4.41.27 PM
  12. In Terminal, press [Control] + [D]
    Screen Shot 2016-05-05 at 4.46.53 PM

Creating A JIRA Plugin

Create an Empty Plugin

  1. In Terminal, enter atlas-create-jira-plugin
    Screen Shot 2016-05-06 at 1.09.58 PM
  2. Enter com.timothycope.demo for the groupID
    Screen Shot 2016-05-06 at 1.13.01 PM
  3. Enter demo for artifactId
    Screen Shot 2016-05-06 at 1.14.21 PM
  4. Enter 1.0-SNAPSHOT for version
    Screen Shot 2016-05-06 at 1.15.36 PM
  5. Enter com.timothycope.demo.plugin for packageScreen Shot 2016-05-06 at 1.21.45 PM
  6. Enter Y
    Screen Shot 2016-05-06 at 1.23.01 PM
  7. Enter cd demo
    Screen Shot 2016-05-06 at 1.32.46 PM
  8. Enter atlas-run
    Screen Shot 2016-05-06 at 1.34.51 PM
  9. If you don’t get the error shown in the screenshot above continue to step 10, otherwise:
    1. Enter nano pom.xml
      Screen Shot 2016-05-06 at 1.39.25 PM
    2. Use the down-arrow key to scroll to the “<properties>” section (near the end of the file)
      Screen Shot 2016-05-06 at 1.41.58 PM
    3. Decrement the <jira.verison> number
      Screen Shot 2016-05-06 at 1.44.11 PM

      • UPDATE: Set the JIRA version to the minimum you want to support. For the available versions see this list. I ended up setting mine to 7.2.0-OD-02-009. Apparently, 1000.0.0 was published on accident.
    4. Press [Control] + [O]
      Screen Shot 2016-05-06 at 1.45.34 PM
    5. Press [Enter]
      Screen Shot 2016-05-06 at 1.46.01 PM
    6. Press [Control] + [X]
      Screen Shot 2016-05-06 at 1.47.30 PM
    7. Enter atlas-run -U
      Screen Shot 2016-05-06 at 2.55.42 PM

      • If you do not see the JIRA instance start, but instead see the same message as before then: Repeat decrementing the version number and running atlas-run -U until it works.
  10. In your browser, open the JIRA url presented in terminal
    Screen Shot 2016-05-06 at 3.04.08 PM
  11. Enter admin for both the Username and PasswordScreen Shot 2016-05-06 at 3.07.11 PM
  12. Select “Continue”
    Screen Shot 2016-05-06 at 3.08.33 PM
  13. Select “Next”
    Screen Shot 2016-05-06 at 3.09.23 PM
  14. Select “Skip quick tour”
    Screen Shot 2016-05-06 at 3.09.59 PM
  15. Enter Test Project for the Project name and TEST for the Key, and then select “Create Project”
    Screen Shot 2016-05-06 at 3.11.18 PM
  16. Select “Skip”
    Screen Shot 2016-05-06 at 3.12.26 PM
  17. Select the gear icon and then “Add-ons”
    Screen Shot 2016-05-06 at 3.14.09 PM
  18. Scroll down the page and you should see two “demos”; one is the plugin and the other its unit testsScreen Shot 2016-05-06 at 3.16.02 PM
  19. Close your browser and in Terminal press [Control] + [D]
    Screen Shot 2016-05-06 at 3.19.37 PM

Update the Generic Plugin’s Data

  1. Enter nano pom.xml
    Screen Shot 2016-05-06 at 3.21.48 PM
  2. Use the down-arrow key to scroll to the <organization> section
    Screen Shot 2016-05-06 at 3.23.27 PM
  3. Change the value for name to “Timothy Cope”
    Screen Shot 2016-05-06 at 3.25.24 PM
  4. Change the value for url to “http://timothycope.com/”
    Screen Shot 2016-05-06 at 3.26.14 PM
  5. Press [Control] + [O]
    Screen Shot 2016-05-06 at 3.27.00 PM
  6. Press [Enter]
    Screen Shot 2016-05-06 at 3.27.27 PM
  7. Press [Control] + [X]
    Screen Shot 2016-05-06 at 3.28.00 PM
  8. Enter atlas-run
    Screen Shot 2016-05-06 at 3.45.31 PM
  9. Navigate to the JIRA url shown in Terminal, login, and view Add-ons
    Screen Shot 2016-05-06 at 3.50.01 PM
  10. Close your browser and in Terminal press [Control] + [D]
    Screen Shot 2016-05-06 at 3.52.06 PM

Setup Eclipse

Getting Eclipse

  1. In your browser navigate to the Eclipse Downloads page for the Luna release
    Screen Shot 2016-05-06 at 3.56.36 PM
  2. Select the link for Eclipse IDE for Java EE Developers, Mac Cocoa 64-bit and then select “Download”
    Screen Shot 2016-05-06 at 3.59.15 PM
  3. Double-click on the .tar file in your Downloads folder
    Screen Shot 2016-05-06 at 4.00.57 PM
  4. (Optional) Drag the “eclipse” folder to Applications
    Screen Shot 2016-05-06 at 4.02.55 PM
  5. Open the eclipse folder
    Screen Shot 2016-05-06 at 4.04.10 PM
  6. Right-click on the eclipse icon and select “Open”
    Screen Shot 2016-05-06 at 4.06.04 PM
  7. Select “Open”
    Screen Shot 2016-05-06 at 4.06.51 PM
  8. (Optional) Right-click on the eclipse icon in your dock and select “Options” -> “Keep in Dock”
    Screen Shot 2016-05-06 at 4.09.04 PM
  9. Enter ~/tutorial and then select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  10. Select “Eclipse” and then “Preferences” from the menu
    Screen Shot 2016-05-09 at 8.20.01 AM
  11. In the search box, type “Installed JREs” and select the result
    Screen Shot 2016-05-09 at 8.21.53 AM

    • Verify that the version is 1.8 (We installed JDK v8 earlier) and close the window by selecting “Cancel”
  12. Select “Help” and then “Install New Packages” from the menu
    Screen Shot 2016-05-09 at 8.28.11 AM
  13. Select “Add…”
    Screen Shot 2016-05-09 at 8.29.56 AM
  14. Enter Sonatype M2Eclipse for Name and http://download.eclipse.org/technology/m2e/releases for Location and the select “OK”
    Screen Shot 2016-05-09 at 8.31.47 AM
  15. Select “Maven Integration for Eclipse” and then “Next >”Screen Shot 2016-05-09 at 8.35.02 AM
  16. Select “Next >”
    Screen Shot 2016-05-09 at 8.35.54 AM
  17. Select “I accept the terms of the license agreement” and then “Finish”
    Screen Shot 2016-05-09 at 8.36.37 AM
  18. Select “Yes”
    Screen Shot 2016-05-09 at 8.40.30 AM
  19. Select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  20. Select “Eclipse” and then “Preferences” from the menu
    Screen Shot 2016-05-09 at 8.43.11 AM
  21. Expand “Maven” and select “Installations” and then select “Add…”
    Screen Shot 2016-05-09 at 8.45.09 AM
  22. Select “Directory…”
    Screen Shot 2016-05-09 at 8.47.07 AM
  23. Browse to your “Applications > Atlassian > atlassian-plugin-sdk-<version> > apache-maven-<version>” directory and select “Open”
    Screen Shot 2016-05-09 at 8.55.59 AM
  24. Select “Finish”
    Screen Shot 2016-05-09 at 8.56.28 AM
  25. Select “apache-maven-<version>” and then select “Apply”
    Screen Shot 2016-05-09 at 8.57.31 AM
  26. Select “Maven” from the left navigation menu and ensure “Download repository index updates on startup” is unchecked
    Screen Shot 2016-05-09 at 8.59.54 AM
  27. Select “OK” and then close Eclipse
    Screen Shot 2016-05-09 at 9.00.49 AM
  28. Delete the .tar file from your Downloads folder
    Screen Shot 2016-05-06 at 4.12.10 PM

Getting the Project Ready to Import into Eclipse

  1. In Terminal, enter atlas-mvn eclipse:eclipse
    Screen Shot 2016-05-06 at 4.16.40 PM
  2. Open Eclipse and select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  3. Select “File” and then select “Import” from the menu
    Screen Shot 2016-05-09 at 9.04.13 AM
  4. Expand “General”, select “Existing Projects into Workspace”, and then select “Next >”
    Screen Shot 2016-05-09 at 9.05.49 AM
  5. Select “Browse…”, browse to the root directory of your workspace, and then select “Open”
    Screen Shot 2016-05-09 at 9.16.23 AM
  6. Select “Finish”
    Screen Shot 2016-05-09 at 9.57.09 AM
  7. Close the Welcome page by selecting the “X” on its tab
    Screen Shot 2016-05-09 at 9.59.03 AM
  8. In the Project Explorer, expand “src/main/resources” and double-click “atlassian-plugin.xml”
    Screen Shot 2016-05-09 at 10.00.18 AM
  9. Select the “Source” tab
    Screen Shot 2016-05-09 at 10.08.10 AM
  10. Close Eclipse
    Screen Shot 2016-05-09 at 10.09.26 AM

Adding to the Plugin

  1. In Terminal, enter atlas-create-jira-plugin-module
    Screen Shot 2016-05-09 at 10.16.11 AM
  2. Enter 21
    Screen Shot 2016-05-09 at 10.16.43 AM
  3. Enter DemoServlet
    Screen Shot 2016-05-09 at 10.18.00 AM
  4. Enter com.timothycope.demo.servlet
    Screen Shot 2016-05-09 at 10.19.08 AM
  5. Enter n
    Screen Shot 2016-05-09 at 10.20.11 AM
  6. Enter n
    Screen Shot 2016-05-09 at 10.20.54 AM
  7. Enter atlas-mvn eclipse:eclipse
    Screen Shot 2016-05-09 at 10.22.51 AM
  8. Enter atlas-run
    Screen Shot 2016-05-09 at 10.31.11 AM
  9. In your browser, navigate to the JIRA url listed in Terminal
    Screen Shot 2016-05-09 at 10.41.04 AM
  10. Log in using admin for the Username and Password
    Screen Shot 2016-05-09 at 10.41.55 AM
  11. Navigate to /jira/plugins/servlet/demoservlet
    Screen Shot 2016-05-09 at 10.47.58 AM

    • The URL comes from the “atlassian-plugin.xml” section <url-pattern>
  12. Close the browser and in Terminal, press [Control] + [D]
    Screen Shot 2016-05-09 at 10.51.32 AM

Adding a Template Renderer to the Plugin

  1. In Terminal, enter atlas-create-jira-plugin-module
    Screen Shot 2016-05-09 at 10.53.58 AM
  2. Enter 1
    Screen Shot 2016-05-09 at 10.54.48 AM
  3. Enter com.timothycope.tutorial.TemplateRenderer
    Screen Shot 2016-05-09 at 11.02.45 AM
  4. Press [Enter]
    Screen Shot 2016-05-09 at 11.03.46 AM
  5. Press [Enter]
    Screen Shot 2016-05-09 at 11.05.02 AM
  6. Enter n
    Screen Shot 2016-05-09 at 11.05.26 AM
  7. Open Eclipse and select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  8. Open “pom.xml”
    Screen Shot 2016-05-09 at 11.10.52 AM
  9. Select the “pom.xml” tab and scroll down to the “<dependencies>” section
    Screen Shot 2016-05-09 at 11.13.09 AM
  10. Add the following dependency:
    Screen Shot 2016-05-09 at 11.16.47 AM
  11. Scroll down to <instructions> and comment out the <Atlassian-Plugin-Key>
    Screen Shot 2016-05-09 at 11.20.35 AM
  12. Save the changes and exit EclipseScreen Shot 2016-05-09 at 11.23.40 AM
  13. In Terminal, enter atlas-mvn eclipse:eclipse
    Screen Shot 2016-05-09 at 11.25.29 AM
  14. Enter atlas-runScreen Shot 2016-05-09 at 11.32.14 AM
  15. In your browser, navigate to the JIRA url listed in Terminal
    Screen Shot 2016-05-09 at 10.41.04 AM
  16. Log in using admin for the Username and Password
    Screen Shot 2016-05-09 at 10.41.55 AM
  17. Select the gear icon and then select “Add-ons”
    Screen Shot 2016-05-09 at 11.35.26 AM
  18. Select “Manage add-ons”
    Screen Shot 2016-05-09 at 11.38.15 AM
  19. Scroll down to the “demo” plugin and expand
    Screen Shot 2016-05-09 at 11.39.55 AM

    • Note that the plugin is currently disabled
  20. Close the browser and in Terminal, press [Control] + [D]
    Screen Shot 2016-05-09 at 11.46.55 AM

Creating the Template

Make the HTML Template

  1. In Terminal enter cd src/main/resources
    Screen Shot 2016-05-09 at 11.50.57 AM
  2. Enter mkdir templates && cd $_
    Screen Shot 2016-05-09 at 11.54.43 AM
  3. Enter touch index.vm
    Screen Shot 2016-05-09 at 11.56.31 AM
  4. Enter nano index.vm
    Screen Shot 2016-05-09 at 11.57.20 AM
  5. Enter the following HTML code
    Screen Shot 2016-05-09 at 12.02.19 PM
  6. Press [Control] + [O]
    Screen Shot 2016-05-09 at 12.03.24 PM
  7. Press [Enter]
    Screen Shot 2016-05-09 at 12.03.39 PM
  8. Press [Control] + [X]
    Screen Shot 2016-05-09 at 12.04.51 PM

Update Servlet to Respond Using the Template

  1. Open Eclipse and select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  2. Open the “DemoServlet.java” file (refresh your project if you do not see it)
    Screen Shot 2016-05-09 at 12.21.24 PM
  3. Add the following imports:
    Screen Shot 2016-05-09 at 12.28.05 PM

    • The second set of imports is due to an issue I ran into
  4. Add the annotation to our class:
    Screen Shot 2016-05-09 at 12.33.48 PM
  5. Add a variable and annotation for the Component Import:
    Screen Shot 2016-05-09 at 12.36.01 PM
  6. Add a variable to hold the template’s location:
    Screen Shot 2016-05-09 at 12.38.02 PM
  7. Add in the constructor
    Screen Shot 2016-05-09 at 12.40.01 PM
  8. Replace the content in the doGet() with the following:
    Screen Shot 2016-05-09 at 12.47.07 PM
  9. Open “atlassian-plugin.xml” and scroll down to the “<component-import>” section
    Screen Shot 2016-05-09 at 12.49.22 PM
  10. Ensure the templateRenderer used is Atlassian’s and not ours by changing the Component Import to:
    Screen Shot 2016-05-09 at 12.51.44 PM
  11. Save and close Eclipse
    Screen Shot 2016-05-09 at 12.53.44 PM
  12. In Terminal, Enter cd ~/tutorial/demo
    Screen Shot 2016-05-09 at 12.56.32 PM
  13. Enter atlas-mvn eclipse:eclipse
    Screen Shot 2016-05-09 at 12.57.54 PM
  14. Enter atlas-run
    Screen Shot 2016-05-09 at 1.05.08 PM
  15. In your browser, navigate to the JIRA url listed in Terminal
    Screen Shot 2016-05-09 at 10.41.04 AM
  16. Log in using admin for the Username and Password
    Screen Shot 2016-05-09 at 10.41.55 AM
  17. Select the gear icon and then select “Add-ons”
    Screen Shot 2016-05-09 at 11.35.26 AM
  18. Select “Manage add-ons”
    Screen Shot 2016-05-09 at 11.38.15 AM
  19. Scroll down to the “demo” plugin and expand
    Screen Shot 2016-05-09 at 1.07.52 PM

    • Note the plugin should be active now that we’ve fixed the Component Import
  20. Navigate to /jira/plugins/servlet/demoservlet
    Screen Shot 2016-05-09 at 1.10.01 PM
  21. Close the browser and in Terminal, press [Control] + [D]
    Screen Shot 2016-05-09 at 1.12.01 PM

Updating the SDK

In the tutorial folder run atlas-update. If you get permission errors the easiest fix is:
sudo chmod -R 777 {path_to_sdk}
For me the path was /Applications/Atlassian.

Further Reading