- 1st release date: April, 2021
- 2nd revision: Oct, 2023
- 3rd revision: Feb, 2024
- author kazurayam
This project presents a custom Keyword (a helper class in Groovy language) named com.kazurayam.ks.TextsDiffer
to be used in Katalon Studio projects.
The class was orignially developed using Katalon Studio v8.6.6 but is not dependent on the Katalon Studio's version. It should work on any newer versions of Katalon Studio as well.
This project reqpository 'katalon-studio-texts-diff' contains 3 sub directories: lib-project
, lib-project
and docs
.
The lib-project
contains a Katalon Studio project where I developed the source code of the Custom keyword for Katalon Studio. The lib-project
has a build.gradle
which build a jar file katalon-studio-texts-diff-xxxxx.jar
that contains the custom keyword's binary. The jar file can be exported into any other Katalon Studio projects.
The app-project
contains a Katalon Studio project where I imported the jar built in the lib-project
. The Test Cases in the app-project
demonstrates how to use the katalon-studio-texts-diff
feature. To get started with the katalon-studio-texts-diff
, you should look at the following code:
Web testers often want to compare 2 text files. The files could be in various format: CSV, JSON, XML, etc. They sometimes just want to check if 2 texts are identical or not, and if not, they would want to see the differences. Katalon Studio does not offer any such feature. So I have created it.
Utilize the java-diff-utils in Katalon Studio.
In the Drivers
directory of your Katalon project, you NEED to install 3 external jar files.
java-diff-utils-4.12.jar
katalon-studio-texts-diff-x.x.x.jar
, the latest versionjava-diff-report-x.x.x.jar
, the latest version
The java-diff-utils-x.x.x
is an open source library in Java for performing the comparison operations between texts. This enables us to generate diff information.
Unfortunately the java-diff-utils
library does not provide a code that generates human-readable reports out of box. To supplement this, kazurayam has developed a java library java-diff-report
. This library provides a set of utility classes that generates human-readable reports easily.
I developed the katalon-studio-texts-diff-x.x.x
library which wraps the java-diff-report
and the java-diff-utils
library to utilize the texts diff feature in arbitrary Katalon Studio projects. With it, you will get a diff report in Markdown format with side-by-side view by just calling a custom keyword.
You want to start Katalon Studio GUI and open your project.
You want to create a new Test Case ex02
(... any name you can choose in fact), of which code looks as follows. You can just copy and paste this:
import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.Paths
import com.kms.katalon.core.configuration.RunConfiguration
/**
* ex02 diff 2 strings and print the stats to console
*/
String text1 = """<doc>
<body>
<section>
<p>Hello, John!</p>
</section>
<p></p>
</body>
</doc>
"""
String text2 = """<doc>
<body>
<section id="main">
<p>Hello, Paul!</p>
<p>Have a break!</p>
</section>
</body>
</doc>
"""
// output
Path outDir = Paths.get(RunConfiguration.getProjectDir()).resolve("build/tmp/testOutput")
Files.createDirectories(outDir)
Path reportFile = outDir.resolve("ex02-output.md")
// pass 2 arguments of String to receive a report in Markdown format
String stats = CustomKeywords.'com.kazurayam.ks.TextsDiffer.diffStrings'(text1, text2, reportFile.toString())
println stats
String report = reportFile.text;
assert report.contains("**DIFFERENT**")
assert report.contains("inserted rows")
assert report.contains("deleted rows")
assert report.contains("changed rows")
assert report.contains("equal rows")
assert report.contains("| 1 |")
assert report.contains("<doc>")
Now you can run this Test Case as usual in Katalon Studio by clicking the green button .
Once done, the script will write a file build/tmp/testOutput/ex02-output.md
. The text will be formatted in Markdown. The file will like this:
### Stats
**DIFFERENT** at 2024-02-07 09:01:07
- inserted rows : 1
- deleted rows : 1
- changed rows : 2
- equal rows: : 5
### Detail
|row#|S|original|revised|
|----|-|--------|-------|
| 1 | | <doc> | <doc> |
| 2 | | <body> | <body> |
| 3 | C | <span style="color:red; font-weight:bold; background-color:#ffeef0"><section></span> | <span style="color:green; font-weight:bold; background-color:#e6ffec"><section id="main"></span> |
| 4 | C | <p>Hello, <span style="color:red; font-weight:bold; background-color:#ffeef0">John!<</span>/p> | <p>Hello, <span style="color:green; font-weight:bold; background-color:#e6ffec">Paul!<</span>/p> |
| 5 | I | | <span style="color:green; font-weight:bold; background-color:#e6ffec"><p>Have a break!</p></span> |
| 6 | | </section> | </section> |
| 7 | D | <span style="color:red; font-weight:bold; background-color:#ffeef0"><p></p></span> | |
| 8 | | </body> | </body> |
| 9 | | </doc> | </doc> |
A Markdown text in raw format is hard to read in a plain text editor. You would definitely require some viewer application tailored for Markdown. For example, I personally use Visual Studio Code, Markdown preview. You can preview the report in VSCode as follows.
This looks nice, doesn't it?
Your input texts sometimes could be very long. Let me assume, for example, that I want to compare the following 2 texts.
Both of them are very long: over 1500 lines. And these texts are slightly different, as the following stats shows:
- inserted rows : 166
- deleted rows : 0
- changed rows : 2
- equal rows: : 1388
Obviously I am only interested in the difference (inserted, deleted, changed); I am not interested in the equal parts. In this case, approximately 90% of lines are not interesting for me. I do not like the diff report to contain the boring equal lines.
So, the java-diff-report
library supports 2 format of diff report: "compact" and "full". You can chose either by specifying a parameter. "compact" is the default. The compact report will trim most of the equal lines. The diff report of the above inputs will contain have only 200 lines, not 1500 lines.The report will look something like this:
Please note that there is a gap between the line#24 and line#1391 where hundreds of "equal" lines are trimmed off. Therefore the report file is small and easy to look through quickly.
The sample Test Case ex02
uses com.kazurayam.ks.TextsDiffer.diffStrings()
method that takes 2 Strings as input. The com.kazurayam.ks.TextsDiffer
class implements more variations of method signature that can take other types: java.io.File
, java.nio.Path
and java.net.URL
.
See the Examples
document for more use cases.
You can have a look at the API documentation of TextsDiffer
class at