Best practice for structuring a Katalon automation repository

Web Testing
,
1

I am new to katalon tool and Automation. What is the best practice for structuring a Katalon automation repository in Katalon studio, when working with multiple applications (e.g., Hospital Registration, Covenant Compliance, Edible, and Dale)?

Specifically:

  • How should the Katalon project structure be designed to support multiple applications within a single repository?
  • What is the recommended Azure DevOps repository and pipeline structure to support CI/CD for these applications?
  • How should the setup accommodate a team of 3 QA engineers working collaboratively, potentially on the same or different applications?
  • Could you provide a diagram or visual representation of the proposed architecture?
2

Based on Katalon best practices and Azure DevOps integration guidelines, here’s the recommended structure for your multi-application automation repository:

1. Katalon Project Structure (Single Repository)

For multiple applications (Hospital Registration, Covenant Compliance, Edible, Dale), use application-scoped folders within one Katalon project:


**`KatalonAutomationRepo.prj`
`├── Test Cases`
`│   ├── Hospital Registration`
`│   │   ├── Login`
`│   │   ├── Patient Registration`
`│   │   └── Billing`
`│   ├── Covenant Compliance`
`│   │   ├── Login`
`│   │   ├── Report Generation`
`│   │   └── Data Submission`
`│   ├── Edible`
`│   │   ├── Login`
`│   │   └── Inventory Management`
`│   └── Dale`
`│       ├── Login`
`│       └── Dashboard`
`├── Object Repository`
`│   ├── Hospital Registration    (mirror Test Cases structure)`
`│   │   ├── UI Elements`
`│   │   └── WS Objects`
`│   ├── Covenant Compliance`
`│   │   ├── UI Elements`
`│   │   └── WS Objects`
`│   ├── Edible`
`│   └── Dale`
`├── Test Suites`
`│   ├── Hospital Registration TSuite`
`│   ├── Covenant Compliance TSuite`
`│   ├── Edible TSuite`
`│   ├── Dale TSuite`
`│   └── Cross-App Regression TSuite (combines all)`
`├── Data Files`
`│   ├── Hospital Registration`
`│   ├── Covenant Compliance`
`│   ├── Edible`
`│   └── Dale`
`├── Profiles                     (environment configs)`
`│   ├── Dev`
`│   ├── QA`
`│   └── Production`
`└── Global Test Listeners        (shared utilities)`**

**Key principles:**

* Create folders matching application modules for easier navigation

* Mirror Object Repository structure with Test Cases for consistency

* Use relative data file paths stored in project directory

## **2. Azure DevOps Repository & Pipeline Structure**



**`Azure DevOps Repository`
`├── /katalon-automation               (main repo)`
`│   ├── KatalonAutomationRepo.prj`
`│   ├── Dockerfile                    (optional custom image)`
`│   └── azure-pipelines.yml`
`├── /pipelines`
`│   ├── hospital-registration-pipeline.yml`
`│   ├── covenant-compliance-pipeline.yml`
`│   ├── edible-pipeline.yml`
`│   ├── dale-pipeline.yml`
`│   └── cross-app-regression-pipeline.yml`
`└── /agent-config`
`    ├── config.cmd`
`    └── run.cmd`**

**Pipeline example (YAML):**



**`trigger:`
`  - main`

`pool:`
`  name: Default`
`  demands:`
`    - agent.name -equals katalonagent`

`steps:`
`  - script: katalonc -noSplash -runMode=console -projectPath="KatalonAutomationRepo.prj" -testSuitePath="Test Suites/Hospital Registration TSuite" browserType="Chrome" -executionProfile="QA" -apiKey="YOUR_API_KEY"`
`    displayName: 'Run Hospital Registration Tests'`**

**CI/CD setup:**

1. Commit Katalon project to Git repository accessible by Azure DevOps

2. Create pipeline in Azure DevOps → Pipelines

3. Configure Katalon agent (download, configure, run)

4. Ensure project includes test cases, test suites, and components

## **3. Team Collaboration Setup (3 QA Engineers)**

| **Role/Task** | **Strategy** |
|:---|:---|
| **Branching** | Use Git branches per application: `feature/hospital-registration`, `feature/covenant-compliance` |
| **Code conflicts** | QA engineers work on different application folders; use Git branch protection for main |
| **Shared utilities** | Keep Global Test Listeners & Profiles in `/shared` folder accessible to all |
| **Test execution** | Run per-application test suites via separate pipelines; cross-app regression runs nightly |
| **Object Repository** | Each QA owns their application's Object Repository folder to prevent duplication  |

**Collaboration workflow:**

* QA Engineer 1 → Hospital Registration

* QA Engineer 2 → Covenant Compliance

* QA Engineer 3 → Edible + Dale

* All → Cross-App Regression TSuite (shared)

## **4. Architecture Diagram**



**`┌─────────────────────────────────────────────────────────────┐`
`│           Azure DevOps Repository (Git)                     │`
`│  ┌───────────────────────────────────────────────────────┐  │`
`│  │         KatalonAutomationRepo.prj                      │  │`
`│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐     │  │`
`│  │  │Hospital │ │Covenant │ │ Edible  │ │  Dale   │     │  │`
`│  │  │Reg TCs  │ │Comp TCs │ │  TCs    │ │  TCs    │     │  │`
`│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘     │  │`
`│  │  ┌─────────────────────────────────────────────────┐  │  │`
`│  │  │         Test Suites (per app + cross-regression)│  │  │`
`│  │  └─────────────────────────────────────────────────┘  │  │`
`│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐     │  │`
`│  │  │Hospital │ │Covenant │ │ Edible  │ │  Dale   │     │  │`
`│  │  │Obj Repo │ │Obj Repo │ │Obj Repo │ │Obj Repo │     │  │`
`│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘     │  │`
`│  └───────────────────────────────────────────────────────┘  │`
`│                                                             │`
`│  ┌───────────────────────────────────────────────────────┐  │`
`│  │           Azure Pipelines (CI/CD)                      │  │`
`│  │  [App 1 Pipeline] [App 2 Pipeline] [Regression]       │  │`
`│  └───────────────────────────────────────────────────────┘  │`
`│                                                             │`
`│  ┌───────────────────────────────────────────────────────┐  │`
`│  │           Katalon Agent Pool                           │  │`
`│  │  [Windows Agent with Katalon Studio + Chrome]         │  │`
`│  └───────────────────────────────────────────────────────┘  │`
`└─────────────────────────────────────────────────────────────┘`
`                              ↓`
`┌─────────────────────────────────────────────────────────────┐`
`│              QA Engineers (3)                                │`
`│  [QA1: Hospital]  [QA2: Covenant]  [QA3: Edible+Dale]       │`
`│         ↓                ↓                  ↓                │`
`│  ┌──────────────────────────────────────────────────────┐  │`
`│  │         Git Branches + Merge to Main                 │  │`
`│  └──────────────────────────────────────────────────────┘  │`
`└─────────────────────────────────────────────────────────────┘`**

This structure ensures:

* **Scalability**: Add new applications as new folders without breaking existing tests

* **Maintainability**: Object Repository mirrors Test Cases

* **Collaboration**: Clear ownership per application prevents conflicts

* **CI/CD**: Separate pipelines per app + nightly cross-app regression
3

HI @olagoke.alli
My recommendation is to design the repository as if it will support multiple applications, multiple QA engineers, and future growth, even if the team is small today.

You have multiple applications:

  • Hospital Registration
  • Covenant Compliance
  • Edible
  • Dale

And a team of 3 QA engineers.

The biggest mistake beginners make is creating separate Katalon projects for every application and then struggling to maintain common code, utilities, test data, and CI/CD pipelines.

A better approach is to create one centralized automation repository with a clear application-wise structure.

Automation-Framework
│
├── Test Cases
│ ├── HospitalRegistration
│ │ ├── Smoke
│ │ ├── Regression
│ │ └── Integration
│ │
│ ├── CovenantCompliance
│ │ ├── Smoke
│ │ ├── Regression
│ │ └── Integration
│ │
│ ├── Edible
│ │ ├── Smoke
│ │ └── Regression
│ │
│ └── Dale
│ ├── Smoke
│ └── Regression
│
├── Object Repository
│ ├── HospitalRegistration
│ ├── CovenantCompliance
│ ├── Edible
│ └── Dale
│
├── Test Data
│ ├── HospitalRegistration
│ ├── CovenantCompliance
│ ├── Edible
│ └── Dale
│
├── Test Suites
│ ├── HospitalRegistration
│ ├── CovenantCompliance
│ ├── Edible
│ └── Dale
│
├── Test Suite Collections
│
├── Keywords
│ ├── Common
│ │ ├── BrowserUtils
│ │ ├── DatabaseUtils
│ │ ├── APIUtils
│ │ ├── ReportUtils
│ │ └── WaitUtils
│ │
│ ├── HospitalRegistration
│ ├── CovenantCompliance
│ ├── Edible
│ └── Dale
│
├── Profiles
│ ├── DEV
│ ├── QA
│ ├── UAT
│ └── PROD
│
└── Include

Why This Structure Works

Application Isolation

Each application has its own:

  • Test Cases
  • Object Repository
  • Test Data
  • Test Suites

This prevents accidental changes affecting another application.

The best practice would be to share Reusable Components amongst teams
Store reusable code under:

Keywords/Common

Examples:

BrowserUtils.groovy
DatabaseUtils.groovy
ExcelUtils.groovy
ApiUtils.groovy

Instead of creating the same code four times, all applications reuse common utilities.

This follows the DRY (Don’t Repeat Yourself) principle.

Team Collaboration Model

Suppose there are 3 QA Engineers.

Engineer Responsibility
QA 1 Hospital Registration
QA 2 Covenant Compliance
QA 3 Edible + Dale

All engineers work in the same repository.

Example:

QA1
 └── Test Cases/HospitalRegistration

QA2
 └── Test Cases/CovenantCompliance

QA3
 └── Test Cases/Edible
 └── Test Cases/Dale

Shared utilities remain under:

Keywords/Common

and are reviewed before modification.

Azure DevOps Repository Structure

A single repository is usually sufficient.

Example:

Azure DevOps
│
└── Katalon-Automation
     │
     ├── Test Cases
     ├── Object Repository
     ├── Keywords
     ├── Profiles
     └── Test Suites

Benefits:

  • Single source of truth
  • Easier maintenance
  • Shared framework
  • Easier onboarding

Avoid:

HospitalRepo
ComplianceRepo
EdibleRepo
DaleRepo

unless applications are completely unrelated and maintained by different teams.

Branching Strategy

A simple Git flow works well.

main
│
├── develop
│
├── feature/hospital-registration
├── feature/compliance
├── feature/edible
└── feature/dale

Workflow:

Feature Branch
      ↓
Pull Request
      ↓
Code Review
      ↓
Develop
      ↓
Main

This prevents engineers from overwriting each other’s work.

Azure DevOps Pipeline Structure

Create one pipeline per application.

Example:

Pipelines
│
├── HospitalRegistration-Pipeline
├── CovenantCompliance-Pipeline
├── Edible-Pipeline
└── Dale-Pipeline

Each pipeline executes only its application’s test suites.

Environment Management

Use Katalon Profiles.

Example:

Profiles
├── DEV
├── QA
├── UAT
└── PROD

Store:

baseUrl
username
password
apiEndpoint

Example:

GlobalVariable.baseUrl

This eliminates hardcoded values.

4

Recommended CI/CD Flow

Developer Deploys Code
            │
            ▼
      QA Environment
            │
            ▼
 Azure Pipeline Triggered
            │
            ▼
 Katalon Smoke Suite
            │
            ▼
 Generate Reports
            │
            ▼
 Publish Results
            │
            ▼
 Regression Execution
5

High-Level Architecture Diagram

                        Azure DevOps
                              │
                              ▼
                    Git Repository
                              │
                              ▼
        ┌───────────────────────────────────┐
        │      Katalon Automation Repo      │
        └───────────────────────────────────┘
                  │              │
                  │              │
                  ▼              ▼

         Common Framework     Application Tests
          (Reusable)          (Business Specific)

      ┌───────────────┐     ┌──────────────────┐
      │ BrowserUtils  │     │ Hospital Reg.    │
      │ APIUtils      │     │ Covenant Comp.   │
      │ DBUtils       │     │ Edible           │
      │ Reporting     │     │ Dale             │
      └───────────────┘     └──────────────────┘

                  │
                  ▼

          Azure Pipelines
      ┌────────┬────────┬────────┬────────┐
      │Hosp.   │Cov.    │Edible  │Dale    │
      └────────┴────────┴────────┴────────┘

                  │
                  ▼

            Test Reports
                  │
                  ▼

              TestOps
6

Additional Best Practices you can foloow

  1. Follow a naming convention:
TC_HR_Login_001
TC_CC_Search_001
TC_ED_Checkout_001
  1. Keep application-specific objects separated.
  2. Move reusable actions into Custom Keywords.
  3. Use Git Pull Requests for all changes.
  4. Enable code reviews before merging.
  5. Store secrets in Azure Variable Groups or Katalon protected variables, not in scripts.
  6. Create Smoke, Regression, and Sanity suites separately for each application.
  7. If the framework grows significantly (10+ applications and multiple teams), then consider splitting into multiple repositories. For 4 applications and 3 QA engineers, a single repository is typically the most maintainable approach.

Long Story short: For your scenario (4 applications, 3 QA engineers), the most practical and scalable solution is one Katalon project, one Azure DevOps repository, shared common framework components, application-wise folder segregation, and separate Azure pipelines per application. This keeps maintenance low, promotes code reuse, and supports collaborative development efficiently.