The branch feature allows you to add and verify changes in a private workspace without affecting test cases or their executions managed across the entire project. This feature enables safe and efficient collaboration within teams.
Table of Contents
1. Use Cases for Branches
- Fix and execute failed test cases in a personal branch without interfering with others' work
- Test upcoming features in the
developbranch and merge them into themainupon release
2. Recommended Branch Configuration
MagicPod's best practice for branch configuration is as follows:
Release Branch: For the production environment
↑
Default Branch: For the development environment・Daily CI execution
↓
Feature Branch: For individual work
Default Branch (main branch)
The role of the default branch is as follows:
- Manage test cases for the development environment
- Automatically executed daily by CI tools
- Serves as the baseline branch
All MagicPod projects are managed with branches. Even if you haven't explicitly created a branch, project resources implicitly exist within the main branch, which is called the default branch. Initially, the branch name is main, but you can change the branch name using the three-dot marker next to the branch name.
We recommend using the default branch for the development environment of your application.
Release Branch
The role of the release branch is as follows:
- Manage test cases for the production environment
- Created for each version (e.g., release-v2.1)
- Used for production monitoring
We recommend creating a new release branch based on the default branch and testing in the production environment each time a new version of the target application is released.
Feature Branch
The role of the feature branch is as follows:
- For individual work
- For verification of modifications and new creations
We recommend creating a feature branch when modifying part of the default branch.
You can use feature branches to make modifications and verifications, and if there are no issues, merge them into the default branch. After merging, the feature branch is deleted.
3. How to Use Branches
A branch is an independent workspace created under a project. It allows you to make and test changes without impacting other branches.
In MagicPod, all projects are managed with branches. Even if no explicit branch is created, the project's resources implicitly exist within the main branch, referred to as the default branch.
Changes validated within a branch can be merged into the default branch when ready.
3-1. Create a Branch
To create a branch, go to a page under your project and click the menu button in the upper-right corner.
After creating a branch, the menu will update, and you will automatically switch to the newly created branch.
In the branch list, you will see the newly created branch along with the default branch. The default branch serves as the primary workspace for the entire project, and you can toggle between branches depending on your workflow.
This setup allows you to edit and execute test cases and shared steps without affecting the default branch.
Please note that new branches can only be created from the default branch. For example, you cannot create the branchB from the non-default branchA.
3-2. Edit Test Cases
Within a branch, you can edit test cases and shared steps as usual. Ensure you're editing the correct branch by checking the branch name displayed in the upper-right menu.
You can review the list of test cases and shared steps edited within a branch on the branch details page. Click "Branch details / merge" in the upper-right menu to access this page.
,
You can view individual changes from the "View Changes" menu.
The following features are unavailable in branches:
- Creating new test cases or shared steps
- Adding/Removing Shared UIs
- ”Add section” and “Organize UIs” features on the UI List screen
- Editing test case names or descriptions
- Viewing UI usage counts
- Reviewing test cases using deleted UIs in the list
If the upper-right menu is not available on a page, the content is shared across all branches. For example, updates to the following resources will apply to all branches:
- Batch run settings
- Test case labels
- Multi-lang data patterns
- Visual diffs
3-3. Execute Test Cases
Branches support both single and batch runs of test cases.
For the single run, the execution method remains unchanged. Execute a test case from the lower-left corner of the test case edit page. Switch branches via the upper-right menu if needed.
For the batch run, you can select a branch before execution begins. After clicking the "Run new batch" button, a branch selection screen will appear before the batch run starts.
You can also specify the branch for command-line batch runs. Refer to the MagicPod Web API page for details on the request format for POST /v1.0/{organization_name}/{project_name}/batch-run/. The request format can also be checked via the "Run from command line" menu in the batch run settings.
3-4. Merge Changes
Once edits and executions are complete, merge your changes into the default branch. Access the branch details page from the upper-right menu to review the list of changes.
If you find unnecessary or unintended changes, discard them via the menu next to each change row. This will revert the resource to its pre-edit state on the branch. If a change is discarded by mistake, you can restore it to a previous version from the history page.
After reviewing all changes, click the merge button to complete the process. Providing a meaningful merge comment helps other team members understand your changes.
Note: Once a branch is merged, it is closed, and no further changes or test runs can be performed in that branch.
⚠️ The following resources are included in branch management (and thus in merge operations):
- Test cases
- Shared steps
- UIs used in test cases and shared steps
- Data patterns
For example, if a new UI is created within a branch but not used in any test cases, it will not be merged.
3-5. Resolve Conflicts
Conflicts occur when the same test case is edited in both the default branch and another branch. A branch with unresolved conflicts cannot be merged. Since such conflicts cannot be resolved automatically, manual resolution is required.
Conflicted resources are flagged on the screen. Open the "Resolve conflicts" menu to open the "Conflict resolution" screen.
In the above case, a conflict occurred because different changes were made to the test case in both the main and develop branches.
In the Conflict resolution screen, the main branch is displayed on the left, and the contents of the develop branch are displayed on the right. The steps in the center are the "Resolved version". After resolving the conflicts, if you press the "Mark as resolved" button in the upper right corner of the screen, the Resolved version's contents will be reflected in the develop branch.
The chunk surrounded by an orange frame cannot be merged automatically due to different modifications made on both the main and development branches.
On the other hand, the chunk not surrounded by an orange frame can be automatically merged. In the example below, only the develop branch added the step to the bottom, so the Resolved version automatically includes the step.
In the chunk surrounded by an orange frame, edit the Resolved version until it is as you want it. Use the arrow buttons to accept the steps you need from the left or right column, or hover your mouse over an unwanted step in the Resolved version and click the x button.
Once you have finished editing the Resolved version for the chunk surrounded by the orange frame, click the "Mark this chunk as resolved" button.
Repeat the above process until all the chunks surrounded by orange frames have been resolved. Then, click the "Mark as resolved" button at the top right of the screen to mark all the conflicts as resolved.
Follow the instructions in the dialog box and save to the history. The contents written in the Resolved version will be reflected in the branch.
Once saved, check if the revised test case works as expected.
4. Supported Versions
When creating and executing tests in a local environment using branches, please update MagicPodDesktop to version 1.19.0 or higher. You can download the latest version of MagicPodDesktop here.
No update is required if you are using a cloud or external cloud service as your test execution environment.
5. FAQ
Q.
After switching branches, I see a "Page Not Found" error. Why?
A.
This error occurs if a resource exists in main but not in develop. For example, switching from main to develop while editing a test case exclusive to main will result in this error.
To avoid this issue, switch branches from the test case list or a similar shared page.
Q.
Why are similar shared UIs sometimes created after merging a branch?
A.
In rare cases, merging creates two shared UIs (e.g., "UI1" and "UI1(1)"). This happens when:
- A test case in
mainuses "UI1" - Create
developbranch, and "UI1" is edited indevelop - A new test case in
mainalso uses "UI1" -
developis merged intomain
To ensure proper functionality, the system creates a new shared UI to differentiate between the test cases. This prevents unexpected behavior in test executions.
Q.
When I resolve a conflict, why do I sometimes end up with two similar UIs in the modified branch?
A.
As with the previous question, there are rare cases where resolving conflicts creates a new UI similar to the original UI (UI1, for example) and a new UI similar to the original UI ( UI1 and UI1(1), for example). This can happen, for instance, in the following cases:
- In
main, set a locatorcss=div[aria-label=111]for a element A in theUI1. - In
develop, set a locatorcss=div[aria-label=222]for a element A in theUI1. - Test case A uses the
UI1in bothmainanddevelop. - Resolve the conflicts of the test case A by including the steps using
UI1, both frommainanddevelop.
In this case, just overwriting UI1 with the contents of the develop branch may cause unintended problems when executing the test case A. Therefore, by creating a new UI, we ensure that the Test case A behaves as intended.
Q.
Why can't I manipulate shared step variables in the Conflict resolution screen?
A.
The shared step variables are automatically taken from the ones actually used in the Resolved version's steps. This prevents mistakes such as forgetting to accept the relevant shared step variables, even though they are used in the Resolved version.