by Suzanne Erin on June 18, 2019

There is no such thing as bug-free code. Even code that was functional on delivery can develop issues over time. Part of owning and maintaining software is always being prepared to address bugs. We often work with clients who are new to software development, so how to test for and report bugs is a perennial topic. Here’s how we like to work with stakeholders to catch and resolve issues.

If you are reporting a bug, the most important thing to be able to do is explain how to reproduce the issue. Often, the majority of the time that a developer spends on resolving a bug is spent just trying to replicate it. Once an issue can be reproduced, then the developer can track down causes and test fixes. Giving the developer as much information as possible up-front in a detailed bug report can save valuable time, and cut down on time lost on back-and-forth questions.

1. Give a step-by-step summary of the actions that lead to the issue occurring.
   If you find it hard to describe, capturing a video or doing a screen-share can be helpful.

2. Confirm the intended behavior.
   For example, saying “this link should go to the Contact Us page” is more helpful than “this link is broken”.

3. Provide technical information.
   Include information about the device, operating system, and browsers you being used, along with their respective versions. For design-related bugs, including screen size and resolution may be useful. This information isn’t always top-of-mind or easy-to-find for the person reporting the bug. In that case, https://mybrowser.fyi is an easy link that generates a report of all this information with a single click.

4. If you can, investigate if the issue happens in other contexts.
   Knowing the situations in which the bug does or does not occur can be valuable information. Other information you can include in your bug report is:

   • Is it intermittent or consistent?
   • Does it happen in other browsers or on other devices?
     
   • Does it happen if you start in a private browser window?
     

5. Write your bug report in a clear and easy to understand format.
   Here is an example of a format we like to use for reporting issues:

Steps to reproduce  
    1.  
    2.  
    3.  

Expected Behavior:  
    Given I'm a [user type]  
    And I [am in this situation]  
    When I [take an action]  
    Then [this desired response happens]  
  
Actual Behavior:  
    Given I'm a [user type]  
    And I [am in this situation]  
    When I [take an action]  
    Then [this wrong thing happens]   
  
Notes:

At Hashrocket, we follow processes to reduce the number of issues that make it to a stakeholder or a user in the first place. Here’s how:

1. Pair Programming
   If we can, we like to pair program, which means that a second set of eyes is “reviewing” the code as it is being written. Two heads are better than one when it comes to implementing code that is more likely to stay stable and maintainable.

2. Test Coverage
   We use test-driven-development (TDD) so that there is a high level of unit and integration test coverage, with continuous integration systems to enforce tests and prevent breaking deployments

3. User-testing on Staging
   We set up a staging environment where both developers and stakeholders can test features as users. This serves as the acceptance process, to confirm the delivered feature meets the stakeholders’ expectations. It also provides an opportunity to try out other user interactions that might not have otherwise been thought through. For example, what if the user decides to exit partway through a workflow? If we didn’t catch these interactions in storycarding, then a thorough testing process can catch issues related to these interactions in staging before they make it to production.

4. Agile Development Practices
   We develop software incrementally and iteratively, using an Agile process. Working on features that are broken down into small parts one-at-a-time allows for increased quality control. Delivering updates incrementally decreases the risk that any issue that makes it through will be show-stopping, and issues are easier to trace back to their source.

5. Managing Technical Debt
   Even after a feature is built, tested and pushed to production, technical debt can lead to problems as the software grows. Adopt development strategies to maintain your application, and reduce the number of issues that arise over time.

Image by Austin Ban