Branch Workflow

info

This page is specific to Connected Projects, where Spaces map to repository branches. For Standalone, the equivalent workflow is a Space's Duplicate and Merge options; see Manual Spaces for the git-to-Standalone equivalents.

A Connected Project is connected to a repository. Each Space in the Project maps to a branch in the repository, and Spaces are created and deleted with the branches. A Space is either a release Space or a sandbox Space:

• Release Spaces are for test execution
• Sandbox Spaces are for test development; they can't run Test Sessions and don't keep spec runs (see Sandbox)

A repository's default branch (e.g. main) is always a release Space. Other branches are sandbox Spaces unless they are the head of an open (non-draft) pull request or match a release pattern. The example below makes every branch with release_ in its name a release Space:

.testspace.yml

manual:

release:
  - "*release_*"  # i.e. "release_56" branch used for test execution

There are two branch flows recommended when testing using Testspace:

• Main flow
• Release flow

Main flow

The Main flow is based on the GitHub flow. The default branch, typically set as main, is used for testing all releases, with branches created from the default branch used for working on new test development.

github.com/org/repo/branches
  └─ main
  └─ testdev/abc_tests
  └─ testdev/xyz_tests
   ..

Releases

The Main flow tests continuously on the default branch (a single release Space).

tip

Update the Space's Description to name the release being tested.

When a release has been completed or deployed, tag the repository, and from the Result's options Pin it (so the retention policy keeps it) and Rename it to name the release and the commit tested.

It is common to follow the same release naming of the repo being tested.

Hotfix

If a hotfix patch is required to be tested a release branch can be used. The following is an example of leveraging a tag.

$ git checkout -b release_42.4.1 tags/v42.4
..
$ git push origin release_42.4.1

Note that the release branch will require configuring:

.testspace.yml

manual:

release:
  - "release_42.*"

Release flow

The Release flow is loosely based on the Gitflow, where a release branch represents the testing for a specific release of the system under test. This flow is especially useful when multiple releases are required to be maintained at the same time.

tip

The Release flow is used when multiple releases are required to be tested and maintained.

A common practice is to name the branch based on the system under test release name.

github.com/org/repo/branches
  └─ main
  └─ release_abc
  └─ release_def
   ..
  └─ testdev/new_tests_for_abc
   ..

To support the Release flow, the non-default branches require configuring:

.testspace.yml

manual:

release:
  - "release_*"

Carry Results

When a new branch is pushed, its Space starts from the Space of the branch it was created from (the branch whose head is the new branch's base commit; otherwise the default branch). That Space's active Result is copied as the new Space's baseline, and its Suites are carried forward in the new Space's sessions.

To assure proper baseline of test results, create your new branch from the appropriate base branch with results. For example:

git checkout release_abc
git checkout -b release_def
..
git push origin release_def

The new branch (release_def) uses the current release_abc Result as its baseline. In the next session, every spec not run is carried from that baseline: the release_abc results at the time of branching.

Reset Results

To start a release branch's Space from a clean slate, without its base branch's results, use Reset from the Space's options menu. See Reset.

Test Development

As with code development, use a branch (a sandbox Space) to develop new tests without affecting other branches. A pull request lets others discuss and review the changes, and follow up with more commits, before they are merged into the base branch.

info

Sandbox Spaces don't keep spec runs and can't run Test Sessions. A branch that is the head of an open (non-draft) pull request isn't a sandbox, so its spec runs are kept.