Beta Feature: Team collaboration

When using JOSF in your team, sharing your test cases should be as easy as a press of a button and with JOSF it is! This is all based on a native implementation of Git and is present as beta feature. If you run into any trouble using this feature, or you have any suggestion, please contact us using our contact form.

Git version control

Git is the most popular version control system and for this reason, JOSF natively supports Git. It is able to automate the synchronization process to share your tests and data with your team. With this feature, you can synchronize changes, switch to a different branch or put your changes into a branch.

The version control feature, with an active branch in JOSF

Set-up

There are two ways to setup synchronization.

1. Your project folder is already under GIT source control

If you’ve enabled GIT on the project folder already, JOSF only requires you to enable the feature to hook into the existing repository. You can do this, by clicking on the unlinked cloud icon and provide the correct username and password credentials.

Provide GIT credentials to start the synchronization process

2. Import a new project, stored in GIT source control

From the workspace overview – when no project is opened yet – you can add a new project from GIT. This requires you to provide the HTTPS URL from the GIT location and your credentials. If you are working behind a proxy, you can enter these after enabling Configure proxy. Next, you can name the new project and JOSF imports the project into your workspace. Note that this does require a valid licence key.

This can be an empty repository, or a repository that already contains a JOSF project.

Import a GIT project
Enter repository details
Name the project
Add the licence and create

Import a GIT project from Microsoft Azure DevOps

For Microsoft Azure DevOps repositories, you need to generate a username and password from there. Once generated, these credentials can be used to clone the GIT project into JOSF.

Log into Microsoft Azure DevOps
Open your project
Go to Repos
Press the Clone-button, to open up the Clone Repository panel
Press Generate GIT credentials
Get the HTTPS URL, the username and the generated password in JOSF to clone your repository from Microsoft Azure DevOps
Enter your name and email address. This data is only used to include into any commits that you apply on the GIT repository
Validate your credentials and clone the JOSF project into your workspace.

Import a GIT project from GitHub

GitHub does not support your username and password as credentials, but instead use a Personal Access Token (PAT). This can be generated from GitHub and used in JOSF to clone your GitHub JOSF project.

Log into GitHub
Go to your personal settings
From the menu, open “Developer settings”
Go to the Personal access token section
Generate a new token
Select the repo scope and give your token a meaningful name
Copy the generated GitHub token (it often starts with ghp_)
Go back to your GitHub repository, and click on the Code button to view the HTTPS URL
Go back to JOSF, Use the HTTPS URL as the repository URL and use the generated token in the username/token field. Leave the password field empty!
Enter your name and email address. This data is only used to include into any commits that you apply on the GIT repository
Validate your credentials and clone the JOSF project into your workspace.

Import a GIT project from other GIT platforms

For most of the GIT platforms, you can use your username and password credentials to clone the GIT project into JOSF.

Enter the HTTPS URL of your repository as the repository URL
Use your username and password as credentials
Enter your name and email address. This data is only used to include into any commits that you apply on the GIT repository
Validate your credentials and clone the JOSF project into your workspace.

If you run into any problem during the clone process, please contact us and we will support you in this process.

Start synchronizing

When you create, modify or delete any data in JOSF (test cases, page objects, features, etc.), JOSF sees this as uncommitted changes. These changes are only present in your local JOSF project. To share these with your team, you can synchronize your changes. JOSF synchronization works with branches and by default, the main branch is activated.

We recommend that you and your team keep working on the main branch, so that any change is directly visible for all team members. This way, any possible data conflict is kept to a minimum. However, it is possible to work with different branches, by using the Switch branch option.

Note that the main branch is tagged with a “main branch” label. Sometimes a main branch is called master.

When you’ve successfully synchronized your changes, other teammembers will get notified that there are incoming changes and they can include your changes in their local JOSF project.

Synchronization states

When using JOSF version control, a new icon appears on screen. This icon represents the state of synchronization and can be one of six types;

Synchronization icons and their respective states. Note how the icons contain the number of changes.

Synchronization icon	Synchronization state
	The synchronization is initializing.
	Indicates that everything is up to date
	You have 1 change that is ready to be shared
	There is 1 incoming change, ready to be collected
	There are multiple changes, both locally and from other team members
	A conflict needs to be resolved. This happens when you change the same files as your team members.

Upon clicking on the synchronization icon, the version control window will pop up.

This view contains the current branch, a more detailed view of the current synchronization state and ways to synchronize your changes. Next to that, you can view the change history.

Sync now

The Sync now button performs a couple of actions in this specific order;

JOSF retrieves any incoming change.
It checks for conflicts with your version
JOSF then shares all changes and locally created branch with your team.

During this proces, JOSF allows you to add a message to the change. Note that a message is auto-generated based on the changes that you have made. Each team member – on the same branch – receive a notification that a new change is ready to be synchronized.

Note that JOSF does not allow for a “retrieve only” or “share only” option. These actions are bundled in one Sync action. Since JOSF uses your GIT repository, you are able to retrieve of share only via traditional GIT ways.
JOSF does not refresh your current screen if you have any test case etc. opened. To see the latest version, you might need to reopen anything currently opened.

Switch branch

This creates a copy of the current test collection and directly switches to that copy, so that any change in the new branch does not impact anything in the original test collection. Newly created branches will be shared with the rest of your team immediately, although changes in that branch must by synchronized manually. Remember to synchronize frequently when on any new branch, as it safely stores the changes that you made into your GIT repository.

Put branch into

After you are done making your changes and you are happy with the result, you can put the branch back into another branch. We recommend you put the branch only back into the main branch. This way you keep it simple and separate things that you are working on with things that you have finished. After JOSF successfully put the changes into the target branch, JOSF will ask if you’d like to remove the original branch. This way, you keep a clean slate of branches.

When a branch gets deleted, the branch is also deleted from your team members branches except for when:

it is the active branch of your team member
that specific branch has unshared changes in it.

In both cases, the branch will tagged as “local branch” at your team members branch overview.

Currently JOSF does not support deleting branches outside of this procedure.

Recommended way of working with branches

Although we recommend working together in the main branch, you are able to work with branches. To explain our recommended way of working with branches, we illustrate things with the following diagram.

In this example, we have a main branch (green), and two feature branches (purple and orange). On the right side, there are changes that you made, and on the left there are changes that a team member has made. Each dot is a synchronization represented over a (dashed) timeline and is explained in the following list.

There is a main branch
You switched to a new branch called “feature/divide-numbers”
Your team member switched to a new branch called “feature/add-numbers”.
You have completed your work, synchronized your work two times and have put your branch back into the main branch.
Your team member has completed its work, synchronized a couple of times and put the branch back to main.
At that point, you switched to a new branch, including the changes of your team member.

This cycle repeats and your JOSF data keeps up to date with each change.

You only put valid changes into the main branch, so that any regression suite you have, can be run from that stable version of the JOSF data.

Remember, this is a recommended way of working with branches. JOSF does not restrict other ways of working with branches, and other work flows are possible.

Resolving conflicts

When you and another team member work on the same data, it could happen that you both make changes to the same file. To reduce this, try and sync as much as possible. But if it does happen that a conflict arises, JOSF helps you with the conflict resolver. At this stage of the conflict resolver, JOSF presents you with the raw format of conflicted files and for each file that contains conflicts, you need to decide what version you’d like to apply. Only after all conflicts are resolved, you can continue with your synchronization proces.

Typically it looks something like this, where you have a list of unresolved conflicted files and a view where it differs. Although it is a technical view, it should be sufficient to decide whether to take your or their version of the same file.

Resolve conflicts by reviewing the raw objects and decide to take either “your” or “their” version before continuing the synchronization

A note on changing the project preferences

JOSF currently stores some project preferences, proxy settings, current active environment and browser, into a single file. If you and your coworker make changing to these details, it could be possible that a merge conflict is created. Once this happens you are required to resolve the conflicted settings file, otherwise JOSF will not continue to work properly. Luckily this is resolved with the same conflict resolver as mentioned before.

Advanced GIT version control

Switch to specific point in history

At this time, we do not support switching to a specific point in history, also known as the git checkout commit command. This sets your repository in a detached HEAD state and JOSF is unable to handle this situation at the moment.