How & Why We Built a Git Workflow to Accelerate API Testing

With the release of ReadyAPI v3.3.0, our all-in-one collaborative API quality platform, the team here at SmartBear completed the first round of work on a rethought Git workflow – all available directly within the tool.

We recognized early when talking about improvements to Git support in ReadyAPI, that it was imperative we take a step back and reframe the existing integration around overcoming obstacles. Especially for the challenges, users face when building projects as part of a small or large group.

(Disclaimer: The author is the Sr. Product Marketing Manager at SmartBear which owns ReadyAPI)

We took some major steps forward with our Git support, and we learned quite a bit along the way. I’m excited to share that journey and our lessons with you as we take a look at how (& why) we rebuilt our Git workflows in ReadyAPI to fit the needs of today’s development teams.

Teams & Testing

We’re fortunate to work closely with users who fill many different roles, have different responsibilities, and in turn have many different expectations about our application. We’re also fortunate that our tooling is
used in a wide array of industries – from highly regulated sectors like Finance and Healthcare to more flexible technology organizations. It’s always illuminating to see exactly how common the challenges that teams face are.

When striving to build and deliver high-quality applications at an increasing rate, it doesn’t matter what project they’re working on, the team they’re part of, or, the industry their organization operates in. Some challenges are universal, especially in an increasingly distributed workforce.

There’s a worldwide current moving us together towards new technologies and delivery strategies. Many organizations are in the midst of what’s coined a digital transformation: the effort to shift legacy applications towards a leaner, more flexible network of smaller services.

We’re seeing teams from around these smaller services, giving them more flexibility to change their applications with the technology that works for them.

It enables them to release at their own pace, and in turn, take on feedback and focus updates based on their application partners and consumers. This adjustment, along with the evolving way they work, reflects a common goal in the technology space – to react more quickly to shifting consumer needs and meet the deployment challenges of the future.

Teamwork and collaboration are essential parts of enabling this transformation. There are countless services (Slack, Bitbucket are two additional tools that are popular with our customers) whose purpose is to enable closer communication and help manage a process around how teams work together.

The ReadyAPI team recognizes we need to be part of a stack and enable collaboration in a way that lets our platform improve quality and process. We can’t be a bottleneck, no testing application can survive if they are.

There’s no cookie-cutter way a team looks or works. We, therefore, recognized that for our application to serve the widest array of needs, we needed to focus on the broader challenges teams face, and not be as prescriptive with pairing our test building tool with where tests are being stored and managed.

Improving the full workflow within the tool can help teams not only overcome current challenges, but also enable them to discover new ways of working together.

Connectivity

The first opportunity in improving Git support was in our connectivity to the platforms and services that provide repository management services. These shared platforms are critical to the team process, and in many cases, are the places an automated process will look for the most recent project updates of a CI/CD task.

The team built a new authentication process called “Account Management,” which lets users input credentials and have them stored at the application level. This way they’re easily reused across interactions with remote providers.

This could come in the form of retrieving a list of repositories, simply pushing changes, or opening a pull request without re-entering authentication values each time.

The ability to reuse and maintain a connection to a remote provider laid the foundation for features in subsequent updates, as well as define an application-level space for us to work with shared credentials.

Interaction

User experience is a critical aspect of any application, but it’s especially important for ReadyAPI since it provides an incredibly wide range of functionality, extensibility, and flexibility.

The user experience of working with a repository was our main focus and saw the release of an updated Git dialog to house all of the repository interactions in a single place.

By bringing these actions into a central place – updating the dialog as changes happen in a project, exposing new functionality to enable more complete Git workflows (such as the ability to create new branches, or open a pull request from with ReadyAPI) – we believe users will more easily make Git interactions a part of their everyday workflow and more clearly understand the relationship between changes in a project they’re working on and its impact on the rest of their team.

Conflict Management

When working as a team, large or small, one of the most common challenges in using Git workflows is cleanly resolving change conflicts. So we introduced a brand new Merge Conflict dialog.

At a high level, it shows three projects – a local version currently being worked, the remote version with changes coming in, and the resulting project that will be used when conflicts are resolved.

By separating these views, users are able to see exactly where conflicts exist in a project. Only now it’s in a visual style that matches our navigator’s project tree and allows users to make more informed conflict decisions.

After going through and choosing resolutions, these can be applied as a batch action, and the project is updated to meet the decisions of the user.

Best Practices

There was a concentrated effort to make our Git interactions and workflows as flexible as possible. We believe the following best practices will help teams create the best workflow when using version control and ReadyAPI while acting as a guide for others looking to build out similar functionality into their testing tools:

Separating tests & code

Some teams that integrate development and testing more closely will look to bring code and tests together into a single repository, which may help simplify the ‘movement’ of these assets together and keep application changes in line with testing changes.

But it does limit the ability for test assets to follow a lifecycle of their own and be broken away from code repositories down the line. We believe that by storing projects in their repository, we can not only enable workflows through the integration in ReadyAPI, but also start a standalone process around test creation, reuse, and versioning.

Making use of branches

Branching strategies are commonplace when working with application code, but in many cases overlooked when talking about test assets. As project team members grow, defining a strategy for how they make and bring changes together is key. If users are working together on a single branch, each small change will have an immediate impact on other's work.

This can create unnecessary noise and undue conflicts that, in many cases, would be resolved through the ‘finalization’ of changes. By working across separate branches, and making use of push/pull workflows, and merging capabilities, teams can more seamlessly work together on separate but related tasks.

Defining a pull request strategy

Many requirements for test changes are part of the definition of done for implementation tasks. In a branching workflow, the ability to merge your changes into a larger main branch is the penultimate step to sharing work. Pull requests are a chance to validate changes and share tweaks before updates moving forward.

They’re also a step still served well as a manual step – having that chance to collaborate on decisions without being a part of the actual test creation process – while in smaller projects automating this stage of the workflow can expedite the larger delivery process. It’s important to understand the benefits and trade-offs of using a manual or automated pull request workflow, as well as explore the benefits of a combined strategy.

The team at SmartBear hopes to help teams build the highest quality software possible and push the needle forward on test creation efficiency.

We’re always looking for suggestions on how we could help improve your team process and we love our users and the larger development community to deliver an API testing platform that solves real challenges.

So if you have any further suggestions or feedback please let us know!

- Happy Testing!

(Disclaimer: The author is the Sr. Product Marketing Manager at SmartBear which owns ReadyAPI)