Create or import test cases

Last updated: October 2026

Test cases are the foundation of your testing strategy in Katalon True Platform. This guide explains how to add test cases, manage their content, and link them to related artifacts.

Choose how to add test cases based on where they are maintained:

Method	Use it when
Import test cases from CSV	You maintain test cases in a spreadsheet or another test management tool.
Import test cases from Azure DevOps	Your test cases are written in Azure DevOps and you want to import them directly.
Upload test cases in a ZIP file	You have a Katalon Studio project or .tc files and do not use a Git integration.
Sync test cases from a Git repository	You maintain test artifacts in a supported version control system.
Create a test case manually	You want to define a test case directly in Katalon True Platform.

Add test cases

Import test cases

If you already maintain test cases outside Katalon True Platform, you can bring them in by importing a CSV file.

Things to Know Before Importing Test Cases:

• Names and paths must start with: Lowercase letters (a–z), numbers (1–9), or an underscore (_)
• Allowed characters within names and paths: Parentheses (), commas ,, periods ., hyphens -, and underscores _
• Please avoid the following:
  • Using .. (double periods) anywhere in the name or path
  • Ending a test case name with a period (.)
• We also recommend splitting your import file into smaller batches (around 500 test cases per file).

You can import test cases from a CSV file into Katalon True Platform. During import, all CSV values are automatically mapped to their corresponding Katalon True Platform fields, including any requirements linkages from your configured ALM integrations (e.g., Jira or Azure DevOps).

1. In your project, navigate to Tests > Test Cases.
2. Click Create > Import Test Cases.
3. Upload your CSV file from your device and click Next.
4. Katalon True Platform will automatically map each field in your CSV file to a corresponding Katalon True Platform field. You can adjust these mappings if needed.
5. Review the mapped fields in the preview, and click Import.

Import test cases from Azure DevOps

requirements

• Azure DevOps must already be linked to this project. See Link Azure DevOps to Project.
• You need the Project Admin role.

If your test cases are written in Azure DevOps, you can import them directly into Katalon Cloud. The import brings over the test case name, description, and test steps with their expected results, and maps Azure DevOps state and priority values to Katalon True Platform Status and Priority.

The import copies the test cases in their current state from Azure DevOps. It is a one-time copy, later changes are not synced or written back to Azure DevOps.

Use this method when:

• You are migrating from Azure DevOps Test Plans to Katalon True Platform and want to keep the test cases you already wrote.
• You run manual tests in Katalon True Platform while Azure DevOps stays your system of record for work items.
• You want to move one team or one feature area at a time, folder by folder, instead of migrating everything at once.

Step 1: Re-sync the Azure DevOps configuration

Re-sync the Azure DevOps configuration so that it is active and up to date before you import.

1. Navigate to your Project > Settings > Integrations.
2. Under ALM & Test Management, expand your Azure DevOps connection and click the Edit (pen) icon on the Azure DevOps configuration you want to import from.
3. Review the configuration and click Proceed.
4. The configuration status changes to Inactive while the sync runs, then returns to Active.

Step 2: Create a destination folder

Import into a dedicated folder so you can review the imported test cases before you move them into your main structure. Skip this step if the folder already exists.

1. Navigate to your Tests > Test Cases.
2. Select the Katalon Cloud repository, click the + Create button, then choose Folder.
3. Enter a Name and click Create.

Step 3: Run the import

1. In the repository tree, select the destination folder.

2. Click the + Create button, then choose Import ADO Test Cases.

3. On the Configuration step, set the source and the destination:

   • ADO integration: Select the Azure DevOps project configuration to import from. The list shows the configurations linked to this project.
   • Cloud repository: Fixed to Katalon Cloud.
   • Destination folder: Prefilled with the folder you selected in the tree. You can change it here.
   note

   The import supports the Katalon Cloud repository only, so the Cloud repository field cannot be changed.

4. Click Next.

5. On the Mapping step, map Azure DevOps values to Katalon True Platform values:

   • Status mapping: Map each Azure DevOps state to a test case status. For example, Design to DRAFT, Ready to PUBLISHED, and Closed to INACTIVE.
   • Priority mapping: Map Azure DevOps priority 1 to 4 to CRITICAL, HIGH, MEDIUM, and LOW.
   note

   The values above are an example. Check the list against your own Azure DevOps project before every import.

6. Click Import.

The imported test cases appear in the destination folder. Status and Priority follow the mapping you set, and Automation Status is To Be Assessed.

Upload test cases via ZIP file

If you don’t use any Git-based integration to sync your repository, you can manually upload either a Katalon Studio project or a ZIP file containing .tc files to import test cases into a Local repository (ZIP Upload) in Katalon True Platform, including the original folder structure inside the ZIP file.

1. Click the + Create button and select Upload Repository.
2. On the Script Repositories page:
   • Enter a Name for the repository (required).
   • (Optional) Add a Description to help identify the repository.
3. In the Upload section, click Choose File and select a ZIP file that contains:
   • A full Katalon Studio project, or
   • One or more test case files (.tc).
4. Click Import to upload and create the repository.

Once the upload is completed, Katalon True Platform extracts the ZIP file and imports all supported test cases while preserving the original directory and folder hierarchy.

Sync test cases from a Git repository

If you use Git-based version control, you can connect your repository to Katalon True Platform to automatically sync test cases, test suites, and test suite collections. Once the integration is set up, your tests will be synced automatically.

To set up repository integration, see:

• GitHub integration
• GitLab integration
• Bitbucket integration
• Azure Repos integration

After successfully configuring your Git integration, Katalon True Platform will automatically sync your test artifacts from the connected repository.

Create test case manually

Use this workflow when you want to create a test case directly in Katalon True Platform and start organizing test steps, ownership, and metadata.

If you want to create automated test cases instead of executing the test manually, you can use Katalon AI Assistant in Katalon Studio to generate the automated test script, sync the project to Katalon True Platform, and then create an automated test run.

1. Navigate to your specific project's UI > Tests > Test Cases.
2. Click Create > Test Case.
3. Fill out the following information:

You want more custom fields?

• Account Admins can configure project-level custom fields in Admin Settings, and those fields become available after the test case is created—use the table below to fill out the built-in fields first.
• Learn more on how to set up Custom Field here.

Field	Requirement	Description
Name	Required	Input the label for your test case. Manual test case names can include these special characters: () , . - _ + & = ' .
Automation Status	Required	Select the current stage of the test case in the automation lifecycle.
Priority	Required	Set the priority level (e.g., High, Medium, Low).
Assignee	Required	Select the person responsible for the test case.
Feature areas	Optional	Parts of the application this test covers.
Test types	Optional	Kind of testing (e.g., Functional, Regression).
Tags	Optional	Project-level labels (up to 50 characters, no special symbols) used to categorize test cases for filtering and analytics. Whatever you add here automatically syncs to linked Katalon Studio projects, so the same tags appear in both tools.
Description	Optional	Input details about your test case.
Precondition	Optional	List the prerequisites for your test case.
Location	Required	Select where you want to save your test case.

4. Click Create.

• Alternatively, click on "Save & Create Another" to immediately input information for an additional test case without navigating away from the current screen.

Try this with Katalon AI

You can also create test cases with Katalon AI Assistant by providing these details and asking the assistant to generate test cases. See Refine requirements and generate test cases for more details.