Commit a9706425 authored by Kevin Moran's avatar Kevin Moran

update README.md

update README.md
parent 7c04c961
Pipeline #34220355 passed with stages
in 12 minutes and 52 seconds
......@@ -17,7 +17,7 @@ This tool is meant for comparing GUI changes between two commits. It can be used
* Quantify GUI changes for client approval and comparison
* Allow user to closely model other application's GUI
## Quick Start
## Getting Started
### Prerequisites
......@@ -96,7 +96,8 @@ $ 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
## Usage
* Run the following command in the GCAT folder, making sure to use __absolute paths__:
......@@ -104,11 +105,11 @@ You will need to run this set of commands twice, once for each screen that you w
java -jar GCAT.jar <screenshotPath1> <xmlDumpPath1> <screenshotPath2> <xmlDumpPath2>
```
GCAT will be run with default settings. A summary and itemized list of changes will be output to the screen, and a full HTML report of the changes will be generated in the newly created folder, Outputs/html/Full-Report.html.
GCAT will be run with default settings. A summary and itemized list of changes will be output to the screen, and a full HTML report of the changes will be generated in the newly created folder, `Outputs/html/Full-Report.html`.
Open this file in your web browser to see the results of the GUI differencing algorithm.
## Usage
### Parameters
To streamline input for the command line, drag and drop the appropriate
files into the command line window. This should copy the absolute path.
......@@ -120,65 +121,73 @@ The input files required are:
* 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]()
### Example Input Files
[newCommitXml]()
[oldCommitImage]()
[oldCommitXml]()
For example files for each input see the following:
## Installation
1. Download GCAT.zip from the root directory. Unzip it to where you keep your applications.
2. Using the command line, navigate to the new folder, and run:
* [newCommitImage](Artifacts/test-files/test-screenshot-2.png)
* [newCommitXml](Artifacts/test-files/test-uiautomator-2.xml)
* [oldCommitImage](Artifacts/test-files/test-screenshot-1.png)
* [oldCommitXml](Artifacts/test-files/test-uiautomator-1.xml)
```shell
java -jar GCAT.jar [optionalParameterTags] <imgPath1> <uidumpPath1> <imgPath2> <uidumpPath2>
```
__It is important that each path is absolute.__
### Usage Flags
The following tags can be added to your shell command to modify the output as follows:
The following flags can be added to your shell command to modify the output as follows:
| Command | Parameter | Default | Effect |
|---|---|---| --- |
|```--htmlreport```| None | None | Opens a visual summary of the GCAT output automatically in your default browser when the analysis is complete. |
|```--violationthreshold```| Integer | 15 | Sets the value that GCAT will use to determine when a visual difference should be counted as an image difference. |
|```--imgDiffthreshold```| Integer | 20 | Sets the value that GCAT will use to determine when objects have moved versus when they have been deleted. |
|```--ignoredareas```| String of the form, "x,y,w,h:x2,y2,w2,h2" where x is the x coordinate of the area, y is the y coordinate of the area, w is width, and h is height. Each area is seperated by a colon, ":"| "0,0,1440,100:0,2372,1440,188" | Set areas on the screenshot that GCAT will ignore when scanning for changes. |
|```--ignoredareas```| String of the form, "x,y,w,h:x2,y2,w2,h2" where x is the x coordinate of the area, y is the y coordinate of the area, w is width, and h is height.| "0,0,1440,100:0,2372,1440,188" | Set areas on the screenshot that GCAT will ignore when scanning for changes. |
## Output
If the tool is run multiple times, the output files are overwritten with the most recent input parameters.
An html page is created with:
* A natural language summary of the changes between the two GUIs
* Detailed information about each change
* Links to view each GUI hierarchy, as well as their maximum common tree.
The directory containing all HTML files can be found at the absolute path: Android-Summarizing-GUI-Changes/Code/guigit/html
* ../commonTree.htm - displays a visual tree hierarchy of the maximum spanning common tree
* ../tree.html - displays the tree hierarchies generated by each commit input
* ../summaryTemplateDefault.html - summary of GUI changes in natural language and detailed changes with images
* ../Landing Page/landingPage.html - navigation between separate HTML files
The directory containing all HTML files can be found at the absolute path: `Android-Summarizing-GUI-Changes/Code/guigit/html`
Explanation of Files:
* `../commonTree.htm` - displays a visual tree hierarchy of the maximum spanning common tree
* `../tree.html` - displays the tree hierarchies generated by each commit input
* `../summaryTemplateDefault.html` - summary of GUI changes in natural language and detailed changes with images
* `../Landing Page/landingPage.html` - navigation between separate HTML files
The `tree.html hierarchy` is color-coded according to the following schema in order to highlight differences:
The tree.html hierarchy is color-coded according to the following schema in order to highlight differences:
* White = Nodes in the tree are exactly the same
* Grey = Layout changes near root of trees
* Red = Tree nodes are different in value or location in the tree
## Our Team
### Members
### Advisors
* [Kevin Moran](www.kpmoran.com)
* [Denys Poshyvanyk](http://www.cs.wm.edu/~denys/index.html)
### Graduate Student Contributors
* [Cody Watson](http://www.cs.wm.edu/~cawatson/)
* [George Purnell](http://georgewpurnell.com/about-me/)
### Undergraduate Contributors
* Shuning Chen
* Louisa Doyle
* Claudia Estes
* John Hoskins
* George Purnell
### Team Leaders
## Citation
If you utilize GCat in your academic work, we kindly ask that you cite our ASE'18 paper:
* Cody
* Kevin
\ No newline at end of file
> Moran, K., Watson, C., Hoskins, J., Purnell, G., and Poshyvanyk, D., “Detecting and Summarizing GUI Changes in Evolving Mobile Apps”, in Proceedings of 33rd IEEE/ACM International Conference on Automated Software Engineering (ASE'18), Montpellier, France, September 3-7, 2018, pp. 543-553
\ No newline at end of file
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