Commit 7c04c961 authored by Kevin Moran's avatar Kevin Moran

Update to README.md

Update to README.md
parent 288921c6
Pipeline #34219941 passed with stages
in 12 minutes and 28 seconds
# Gui Change Analysis Tool (G-CAT)
# Android GUI Change Analysis Tool (G-CAT)
## Project Summary
......@@ -6,12 +6,12 @@ Mobile applications evolve at a rapid pace. During the development lifecycle of
Because mobile applications are heavily GUI-driven, much of the functionality is tied to code related to the user interface. Therefore, changes to the user interface are of paramount importance for developers to understand and document in order to maintain a detailed working knowledge of an evolving codebase.
The purpose of this project is to develop a system to automatically detect, summarize, and document GUI-changes in mobile apps. This project will require the development and application of a differencing algorithm for attributed trees representing the hierarchical structure of mobile GUIs combined with computer vision techniques for detecting style and color differences.
The output of the tool will be detailed release notes that summarize the changes of a mobile GUI between two different releases or versions. Ideally the end product could be integrated as a plugin to an existing issue tracker (GitHub, GitLab).
To help aid in the comprehension of GUI changes in evolving mobile apps we have developed GCat which is capable of automatically detecting, summarizing, and documenting GUI-changes in mobile apps.
## Use Cases
This tool is meant for comparing GUI changes between two commits. It can be used to:
* Optimize front-end development when working in a large group of developers
* Simplify GUI backtracking by highlighting where changes have occurred
* Quantify GUI changes for client approval and comparison
......@@ -20,37 +20,84 @@ This tool is meant for comparing GUI changes between two commits. It can be used
## Quick Start
### Prerequisites
GCAT takes two screenshots, and two XML [uiautomator](https://stuff.mit.edu/afs/sipb/project/android/docs/tools/help/uiautomator/index.html) dumps as input.
We recommend using The Android Debug Bridge, or [ADB](https://developer.android.com/studio/command-line/adb.html) to do this.
* Download and install ADB
Gcat accepts two screenshots, and two XML [uiautomator](https://stuff.mit.edu/afs/sipb/project/android/docs/tools/help/uiautomator/index.html) files as input.
We recommend using The Android Debug Bridge, or [`adb`](https://developer.android.com/studio/command-line/adb.html) to capture screenshots and UI-dumps from a target app screen running on an Android device or emulator. You can find instructions on installing `adb` on your computer [here]().
We have developed GCat to run on macOS, Linux, and Windows. However, the development, documentation, and testing of GCat is primarily conducted on Linux and macOS, and thus these are the recommended platforms for this tool.
### Installation
* Download GCAT.zip
* Unzip GCAT.zip somewhere on your computer.
### Installing and Running the GCat Binaries
We developed GCat using GtiLab's CI system, so that every commit to the public-master branch of GCat is autaomtically tested and built to help ensure the quality of the tool. While we strive to keep the public-master branch as stable as possible, there may unexpected or undocumented changes as we continue development on the tool. Therefore users can also utilize one our stable [tagged releases](https://gitlab.com/SEMERU-Code-Public/Android/gcat/tags).
* Download the [latest build](https://gitlab.com/SEMERU-Code-Public/Android/GCat/-/jobs/artifacts/public-master/download?job=build) of the public-master branch, or one of the [stable releases](https://gitlab.com/SEMERU-Code-Public/Android/gcat/tags)
* Unzip the downloaded directory
* Depending on your operating system, you may need to give the following files permission to run:
* GCAT/libs/pid-linux/perceptualdiff
* GCAT/libs/pid-windows/perceptualdiff.exe
* GCAT/libs/pid-mac/perceptualdiff
* Navigate to the newly created GCAT folder.
* `GCAT/libs/pid-linux/perceptualdiff`
* `GCAT/libs/pid-windows/perceptualdiff.exe`
* `GCAT/libs/pid-mac/perceptualdiff`
* Move the `Gcat.jar` executable out of the `target` folder and into the root of the downloaded directory. If you are on a Unix-Like system, you can run the following commands from the root of the downloaded folder:
```shell
$ mv /target/GCat.jar ..
$ rm -r /target
```
* Now you are ready to run the GCat executable as outlined later in the README.
### Importing and Compiling the Project in Eclipse
GCat was developed using the Eclipse IDE and its dependencies and tests are managed using Maven. We include all the necessary files to import the project directly into Eclipse.
* First clone the GCat repo on your local machine.
* In Eclipse, simply go to File --> Import, and then select the "Existing Java Projects into Workspace" option.
* Click the "Next" button, and then under the "Select root directory" option on the next screen browse to the root of of the cloned GCat repo.
* Click the "Finish" Button to complete the import process.
* The project will now automatically compile using Eclipse.
### Generating Input
* Connect to the Android instance running your app using adb.
### Compiling GCat from the Command Line
You can also compile and test GCat from the command line using maven. In order to to do this, you must have maven installed on your machine and in your `$PATH`.
To compile the project into a `.jar` without running any tests:
* Clone the GCat repo to your local machine
* Open a bash shell in the root of the cloned repository and enter the following command:
To get screenshots of the two GUIs you want to compare (more info [here](https://developer.android.com/studio/command-line/adb.html#screencap)):
```shell
adb shell screencap /sdcard/screenshot.png
adb pull /sdcard/screenshot.png guiscreenshot1.png
$ mvn -Dmaven.test.skip=true package
```
To get the uiautomator dumps of the two GUIs you want to compare (more info [here](https://stuff.mit.edu/afs/sipb/project/android/docs/tools/help/uiautomator/index.html))
To run all tests associated with the GCat project and compile the project into a `.jar`:
* Clone the GCat repo to your local machine
* Open a bash shell in the root of the cloned repository and enter the following command:
```shell
$ mvn package
```
### Capturing Input Files from a Device or Emulator
In order to use GCat, you must first capture a set of four input files from an app running on a device or emulator connected to your computer. To do this, make sure you have `adb` installed on your computer and connect the device or emulator to your computer using `adb`.
To capture screenshots of the two GUIs you want to compare (more info [here](https://developer.android.com/studio/command-line/adb.html#screencap)) you can run the following command:
```shell
adb shell uiautomator dump dump1.xml
$ adb shell screencap /sdcard/screenshot.png
$ adb pull /sdcard/screenshot1.png screenshot1.png
```
Run these commands twice total, once when the Android instance is open to each GUI you want to compare.
To get the uiautomator dumps of the two GUIs you want to compare (more info [here](https://stuff.mit.edu/afs/sipb/project/android/docs/tools/help/uiautomator/index.html)) you can run the following commands:
```shell
$ adb shell uiautomator dump /sdcard/dump1.xml
$ adb pull /sdcard/dump1.xml dump1.xml
```
You will need to run this set of commands twice, once for each screen that you wish to analyze, which should result in a screenshot and UI-dump for each version of the app that you want to compare.
### Running GCAT
* Run the following command in the GCAT folder, making sure to use __absolute paths__:
```shell
......@@ -62,23 +109,26 @@ GCAT will be run with default settings. A summary and itemized list of changes w
Open this file in your web browser to see the results of the GUI differencing algorithm.
## Usage
To streamline input for the command line, drag and drop the appropriate
files into the command line window. This should copy the absolute path.
The input files required are:
* New commit png file containing screenshot of entire screen - referenced in instructions as the absolute path imgPath1
* New commit xml file generated using UiAutomator - referenced in instructions as absolute path uidumpPath1
* Old commit png file containing screenshot of entire screen - referenced in instructions as absolute path imgPath2
* Old commit xml file generated using UiAutomator - referenced in instructions as absolute path uidumpPath2
* Previous commit `.png` file containing screenshot of entire screen - referenced in instructions as the absolute path `imgPath1`
* Previous commit `.xml` file generated using UiAutomator - referenced in instructions as absolute path `uidumpPath1`
* New commit `.png` file containing screenshot of entire screen - referenced in instructions as absolute path `imgPath2`
* New commit `.xml` file generated using UiAutomator - referenced in instructions as absolute path `uidumpPath2`
For example files for each input see the following:
[newCommitImage](../Code/guigit/src/test/res/com.pandora.android/com.pandora.android-original1-1.png)
[newCommitImage]()
[newCommitXml](../Code/guigit/src/test/res/com.pandora.android/com.pandora.android-original1-1.xml)
[newCommitXml]()
[oldCommitImage](../Code/guigit/src/test/res/com.pandora.android/com.pandora.android-original.png)
[oldCommitImage]()
[oldCommitXml](../Code/guigit/src/test/res/com.pandora.android/com.pandora.android-original.xml)
[oldCommitXml]()
## Installation
1. Download GCAT.zip from the root directory. Unzip it to where you keep your applications.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment