Using Git Submodules to share Test Artifacts in Katalon Studio
While working on a Katalon Studio project, you might want to use test artifacts from external resources. You can manually share test artifacts with the Test Artifacts Sharing feature provided by Katalon Studio. See: Test Artifacts Sharing.
To maintain and update shared resources easily, you can also integrate them as Git submodules. Git submodules enable you to incorporate and track the version history of external resources. To learn more about Git submodules, you can refer to the official Git documentation: Git Tools - Submodules.
This tutorial shows you how to use the Git submodule feature to incorporate test artifacts from an external resource, such as Test Cases, Test Objects, Profiles, and Keywords. In our example, we cover common tasks such as adding, updating, and removing a custom keyword package as a submodule in a test project.
You can download the sample project here on our GitHub repository: Healthcare Tests.
Requirements
- An active Katalon Studio Enterprise license.
- A Katalon Studio project configured as a Git repository. To configure Git integration in a project, refer to this guide: Git Integration.
- A custom keyword repository hosted on GitHub.
Add a Git submodule to a project
The structure of our test project repository is as follows:
The content of the custom keyword package on GitHub is as follows:
Katalon Studio stores test keywords in the Keywords folder. Therefore, we want to add the custom keyword package to the Keywords
folder as a Git submodule.
Follow these steps:
-
Open Terminal, then go to the
Keywords
folder in the test project directory. For example, we go to thehealthcare-tests/Keywords
folder:$ cd healthcare-tests/Keywords
-
To add the keyword package from GitHub to our test project repository, we use the
git submodule add <URL>
command. The URL in the command is the URL for the keyword package hosted on GitHub.# Add the keyword repository from remote as a submodule
$ git submodule add https://github.com/<username>/mykeywords.gitIf you check the status of the project repository with the
git status
command, you can see two changes: the.gitmodules
file and the added submodule folder. The.gitmodules
file contains information about added submodules, including directory paths and URLs for cloning and fetching.In our case, the status output shows the
.gitmodules
file and themykeywords
folder as follows:On branch master
Your branch is up to date with 'origin/master'.
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
new file: ../.gitmodules
new file: mykeywords -
Add and commit the changes.
Once the submodule is added to the main repository, you can track the changes of the submodule like in a normal repository. Here we track the submodule by adding and committing the changes to our test project repository.
$ git add .
$ git commit -m "Add the mykeywords package as submodule" -
Verify that the custom keyword package is added to the test project. Open the project in Katalon Studio, from the main toolbar, select Project > Refresh.
Katalon Studio should display the added package with keyword files in the Keywords section.
Update a Submodule
The keyword package hosted on GitHub might change following an update from other collaborators.
In our example, a new custom keyword file is added to the remote repository:
To update the local keyword package with the latest files from the remote repository, we use the git submodule update --remote
command.
Follow these steps:
-
Open Terminal, then go to the
Keywords
folder in the test project directory.$ cd healthcare-tests/Keywords
-
Update the submodule with the
git submodule update --remote
command.The
git submodule update --remote
command updates the keyword package by pulling all the files from the remote repository into the package folder.$ git submodule update --remote
If you check the
mykeywords
package folder, you can see that the new keyword file is added.$ ls mykeywords/
HighlightElement.groovy
VerifyDrodownValues_AlphabeticalOrder.groovy
VerifyExpectedAndActualOptionsInDropdown.groovy
refreshBrowser.groovy # Added keyword file -
Add and commit the changes.
$ git add .
$ git commit -m "Add the new keyword after submodule update" -
Verify that the new keyword file is added. Open the project in Katalon Studio, from the main toolbar, select Project > Refresh.
Katalon Studio should display the updated keyword file.
Delete a submodule
Git provides no simple interface to delete a submodule. To fully remove a submodule, we must remove the submodule folder and all references.
In our case, we want to fully remove the custom keyword package from the test project repository.
Follow these steps:
-
Open Terminal, then go to the
Keywords
folder containing the submodule in the test project directory.$ cd healthcare-tests/Keywords
-
Remove the references to the submodule and the submodule folder.
Here we remove all the references to the keyword package
mykeywords
and themykeywords
folder.# Remove the reference in the .git/config file
$ git submodule deinit -f mykeywords
# Remove the reference in the .git/modules folder
$ rm -rf ../.git/modules/Keywords/mykeywords/
# Remove the tracked folder from Git index and the folder itself
$ git rm -f mykeywords -
Commit the changes.
$ git commit -m "Remove the keyword submodule"
-
Verify that the custom keyword package is removed. Open the project in Katalon Studio, from the main toolbar, select Project > Refresh.
You should see that the custom keyword package is now removed from the Keywords section.