Code reviews bring many benefits to the process of writing and delivering software:

• Ensures consistency through your codebase.
• Teaches all members of the review (helps knowledge transfer).
• Builds contextual awareness regarding what might affect other parts of the team
• Helps avoid breaking builds
• Casts fresh eyes over a code change to search for optimisations and simplifications in the change.
• Promotes quality and helps make sure no one forgot or missed anything.

Google has 1,918 repositories on their GitHub across multiple languages, and even more that aren't open source.

One of their codebases is shared by over 25,000 Googlers, and typically has 40,000 commits daily (16,000 human changes, and 24,000 by automated systems). Each day it has to serve around 800,000 queries per second during peak times.

Google has published their engineering practices, so let's see how they review code at their scale, with so many commits a day.

Google refers to changes in their codebases as CLs standing for change lists. It's just a unit of work / piece of code going through review.

How to Prepare for Code Reviews

Firstly, before you even think about the code review process, try and focus on who will do the review. Try to pick a subject matter expert. Pick someone who is familiar with this codebase or area of the codebase.

Sometimes this may even mean having different people review different parts of the code. But less than 25% of code review's at Google have more than one reviewer.

Getting someone to respond in a timely manner is also important. To avoid bottle necks and overloading individuals, just CC reviewers onto the change to review it at their convenience if they want to.

How to Run Fast Code Reviews

Code reviews should be completed quickly. The maximum length of time for a review should be one business day.

Why the urgency? I've personally had QA's sometimes take weeks or longer.

• It becomes a blocker. Although the author of the code moves onto new work, new changes start to form a back log, and the delays can build up to weeks or months.
• Developers feel frustrated. If the reviewer asks for major changes but only responds every 3 days, it is frustrating for the developer working on that change. But with quick responses, whenever you require explanation of exactly what you need to do, the frustration fades away.
• Code quality can degrade. If your reviews are always slow, developers are less likely to do code clean ups, refactoring work or general code improvement ("If my reviewer won't reply for 4 days what's even the point?"), and the code quality submitted in the reviews is more likely to go down.

The main reason code reviews can be fast is because they're small. Rather than sending a 1,000 line CL, they're separated into multiple CL's – pushing 10 smaller changes of 100 lines for example.

Google also has emergencies where code changes have to be made quickly to resolve major problems in production. In these cases, code quality is relaxed. This review should immediately become the reviewers first priority. There are some examples of emergencies Google has faced here if you're curious.

Google's Code Review Standards

The key rule Google emphasizes is:

Reviewers should generally approve a change once it definitely improves the overall code health, even if it isn't perfect.

The key point Google seem to be making is that perfect code doesn't exist. If it makes it better, that is enough.

It's definitely a balancing act between something being better, and how much better it could be. If you could add more feedback to make significant improvements, there may need to be more work done on the code.

What Googlers Look for in Code Reviews

When doing code reviews, Google focuses on these elements according to their engineering practices documentation:

Design: Is the code well-designed and appropriate for your system? Does this change belong in your codebase, or in a library? Does it integrate well with the rest of your system?

Functionality: Does the code behave as the author likely intended? Is the way the code behaves good for its users? Mostly, we expect developers to test CLs well-enough that they work correctly by the time they get to code review.

Complexity: Could the code be made simpler? Would another developer be able to easily understand and use this code when they come across it in the future? Is it over-engineered for its current use case?

Tests: Does the code have correct and well-designed automated tests? Will the tests actually fail when the code is broken? Will they start producing false positives? Does each test make simple and useful assertions?

Naming: Did the developer choose clear names for variables, classes, methods, etc.?

Comments: Are the comments clear and useful? Ensure where sensible comments explain why something is being done, rather than how.

Style & Consistency: Does the code follow our style guides?

Documentation: Did the developer also update relevant documentation?

Google has style guides for multiple languages like C++, Swift, HTML/CSS, Lisp, JavaScript and more.

Having a document that everyone can refer to helps standardise the code. It also helps clarify what the expectations are in the review process.

How Googlers Review Code

There is a three-stage process for code review in Google's engineering practices. Here's a list of things you'd need to cover if you were to review:

1. Get a high level overview of the change
2. Examine the main parts of the change
3. Look through the rest of the code, in a sensible order

Let's go over each step in more detail.

1. Get a High Level Overview of the Code Change

Look at the code change's description/summary. Does it all make sense? For example, if someone is changing a codebase that is being deleted next week, push back on the change courteously, and explain why the change doesn't look needed anymore.

It's inefficient if people are spending time on work that isn't actually needed, so have a look at your development life cycle and see why this might be happening. The earlier you can catch these issues the better.

In order to get a high level overview of the code, you may want to briefly scan the code components to see how it all works together.

If you see a serious architectural problem or something majorly wrong, you should share your observations immediately at this stage. Even if you don't have time to review every single other element of the review. Reviewing the rest may well even end up being a waste of time if the architectural problems are severe enough.

Aside from this, there are 2 major reasons why you should send your review comments immediately:

• Googlers will often email a change, and then immediately start new work based on that change. If the change in review need serious adjustments, they may be building on something that needs to be significantly changed.
• Big changes to the CL may take a while to finish. Developers all have deadlines and it's courteous to try and help them meet them by letting them start rework as soon as possible.

2. Examine the Main Parts of the Code Change

Once you have had an overview, review the "main" parts of the change.

Find the file or files that are central to the CL. Often, there is one file that has the largest number of changes, and it’s the major piece of the CL.

Spend most of your focus reviewing these pieces. This provides context to all the smaller pieces, and generally makes it faster to review.

If the CL is too large for you to get a good overview and understand the flow, it's a good sign the developer should be splitting up their CL into smaller changes.

3. Look Through the Rest of the Code, in a Sensible Order

Once you have a good overview of the change, it's time to drill down into the details and go file by file.

Each reviewer generally does this differently. Some go in the order that the version control presents to them and some pick a particular order. Choose what makes sense to you. It's important to just review everything, and miss nothing.

Review Every Line of Code

Don't miss or skim important details. Sometimes there might be config files, or generated code you can scan briefly looking for irregularities. But your job here is to be very thorough and carefully scrutinise the code.

Make sure you think about bugs, race conditions, alternate approaches, conciseness, readability, and so on.

If you can't understand the code, it's highly likely other developers won't be able to either, and should ask the developer to clarify it.

Understand the Context

Often times the version control software will only show the changed lines. But it's important to read the lines before and after, or the whole file, to ensure you understand exactly what the change is doing.

You may only see someone adding 2 more if blocks in a change. But if you look at the context you might see that the if else block now has 15 different if's inside it. Then you can reject the code change and properly improve the code quality in this area, rather than making it worse.

Remember code degradation happens slowly, with every change that goes in. Our main aim is to ensure the quality trends consistently up, and we never go backwards.

How Googlers Write Code Feedback

Google has some specific sections covering how to do code reviews courteously, and respectfully. This isn't in opposition to being clear and as helpful as you can to the developer. The golden rule here is to make comments about the code and not the developer.

What to Do:

####

Ask for the why: If it is unclear why the author is doing things a certain way, feel free to ask why they made a particular change. Not knowing is OK, and asking “Why” leaves a written record that will help answer this question in the future. (And sometimes, “I'm curious, why did you decide to do it that way?” can help the author to rethink their decision.)

Find an end: If you like things neat, it’s tempting to go over a code review over and over until it’s perfect, dragging it out for longer than necessary. It’s soul-deadening for the recipient, though. Keep in mind that “LGTM” does not mean “I vouch my immortal soul this will never fail”, but “looks good to me”. If it looks good, move on. (That doesn’t mean you shouldn’t be thorough. It’s a judgment call.) And if there are bigger refactorings to be done, move them to a new CL. (Source)

What Not to Do

Don't use extreme or very negative language: Please don't say things like “no sane person would ever do this” or “this algorithm is terrible”, whether it’s about the change you're reviewing or about the surrounding code. While it might intimidate the reviewee into doing what you want, it’s not helpful in the long run - they will feel incapable, and there is not much info in there to help them improve. “This is a good start, but it could use some work” or “This needs some cleanup” are nicer ways of saying it. Discuss the code, not the person.

Don't bikeshed: Always ask yourself if this decision really matters in the long run, or if you're enforcing a subjective preference. It feels good to be right, but only one of the two participants can win that game. If it’s not important, agree to disagree, and move on. (Source)

Remember code reviews can sometimes trend towards finding issues or discussions with code and not praise.

If your reviewer has addressed your comments, or they have done some optimisation or smart code you like, thank them. Say you like the approach / how they have solved an issue.

Conversely, thank the reviewer if they thoroughly explain what they want and promptly answer your questions.

I have had some reviews where reviewers have put huge comments explaining something I misunderstood and I can still remember who it was and what they said.

How to Handle Pushback in Code Reviews

Sometimes the developer who is receiving the review might disagree with the changes that you're proposing. Here's how to handle that.

Consider That They Might Be Right

Sometimes the developer is closer to the code and how it works, and they may be right. If they are, move on from that discussion point and leave that code as it is.

But if they're not, or they've misunderstood something, you should insist on the change. Respond to what the developer initially challenged you on, and explain your reasoning courteously.

Code quality improvements tend to happen in small incremental steps, and review is one way it happens. Insist on the code improvement, even if it means extra work for the developer.

Try to Avoid "I'll fix this later..."

One of the most common issues in reviews is not that people disagree whether the code change is necessary, but rather that they want to do it under a different ticket or do it later. So if you pass this review, they assure you that they will follow up later and fix the issues.

Generally speaking, following up later rarely happens. This doesn't mean there's something wrong with the developer or their work ethic. But it's easy to forget, have priorities change, or even just get lost in their queue of work.

Insist that the work gets done now. There is no real fantastic gain to merging changes in the codebase you have to immediately fix. You are just adding technical debt that might be followed up on later, or might be forgotten. Fixing lots of tickets later is an easy way for quality to drop.

The only exception to this is emergencies, which involve the highest priority bugs Google deals with where there is something seriously wrong. This could be services going down, or errors crashing people's pages in production.

There is naturally an eagerness to merge changes ASAP, and the review might accept slightly lower quality, with a follow up fix immediately being written. The main point is that the first change removes the emergency, and the second change fixes it properly.

Conclusion

I hope this has explained some helpful concepts Google makes use of in their code review process. I wrote this to better cement it into my own mind, and was curious about how other companies handle the QA process.

I found that there are quite a few points that I can take away and apply to the reviews I conduct.

The document I referred to throughout this article can be found here.

I share my writing on Twitter if you enjoyed this article and want to see more.

So how can we use Postman to both test our existing APIs and understand how they work?

• What is Postman?
• What are we going to build / learn?
• Part 0: Getting set up with Postman
• Part 1: An introduction to Postman
• Part 2: Creating a new Postman request to GET info about Squirtle
• Part 3: Creating a collection of requests in Postman for the PokéAPI
• Part 4: Making POST requests with Postman to translate sentences to sound like Yoda
• Part 5: Authenticating requests to the Lord of the Rings API with an API Key

What is Postman?

Postman is a tool teams can use to reliably test APIs using easy to use configurations. It comes stocked with features you would expect when dealing with APIs, including authentication, setting headers, customizing the payload, and a bunch more that help reduce the friction of using an API.

And it’s not just for testing. The beauty is that this can be used for many aspects of working with APIs for many different members of the team. Maybe a Project Manager wants to verify that things work or might find it easier to make a change straight with the API, or a QA Engineer needs to make sure everything still works, or a developer wants to actively make changes while working on the API itself.

The best part about it – Postman provides collaboration features. The free tier includes exporting and importing collections of saved API requests as well as creating shared links. If you're part of a team, they have paid tiers that allow you to sync up your collections to make sure everyone has the most recent and up to date collection.

What are we going to build / learn?

We’re going to walk through two different example APIs to cover the concepts of Postman.

First, we’ll walk through some simple HTTP requests with a public API for Pokémon.

We’ll then use the Yoda Translator API for one part to demonstrate how to make specific HTTP requests.

Once we understand how the basics work, we’ll use the Lord of the Rings API to learn how authentication works with APIs. For this, you’ll need to register for a free account for an API key.

Part 0: Getting set up with Postman

Before we get started, you’ll need Postman in order to follow along with this walkthrough. The good news, is Postman is available for free on Mac, Windows, and Linux, so you should be able to find a version that works for you.

Get Postman: https://www.postman.com/downloads/

Once downloaded, go through the standard installation instructions, open it up, and we should be ready to go!

Part 1: An introduction to Postman

The first time you open up Postman you’ll immediately be shown a launchpad with a bunch of options to get started.

It might seem a bit overwhelming, but let’s break down some of the key concepts that we’ll need to know.

Requests

A request is kind of what it sounds like, it’s a specific API request. This will be a single type of request, whether it’s a GET or POST to a specific endpoint. You’ll want to create new requests for each type of endpoint which will allow you to move between them when testing.

Collections

A collection is a group of requests. This is handy for organizing your requests into different groups. This could be as simple as two totally different APIs (ie. Twitter vs Slack) or it could be two different groups of APIs for a single API (ie. Twitter Tweets API vs Twitter Accounts API).

Authorization

Authorization is how requests are authenticated with an API, whether by a person making a request or by a computer making that request on your behalf. This commonly comes in the form of an API key which can be a static value assigned to your account or dynamically generated with tools like OAuth.

Environments

Environments will allow you to configure your endpoints to use specific variables that make it easier to use the same endpoints between different environments. For instance, you might have the same /profile endpoint on both your production and development environments, but they have different domains. Environments lets you manage a single request with a variable domain.

Workspaces

We won’t go too far into workspaces in this post, but it allows you to manage and organize different sets of collections. Imagine if you want to use Postman for both work and a personal project, you might have a Work workspace as well as a Personal workspace.

For the purposes of this article, we’ll be covering Requests, Collections, and Authorization.

Part 2: Creating a new Postman request to GET info about Squirtle

Now that we have a better understanding of the different terminology, let’s actually create a request.

At the top left of the UI you should see a but orange button that says New. Go ahead and click that and then select Request.

Before we get into the request itself, it requests a few things.

This first thing requires is a name. We’re going to start off by requesting information about the Pokémon Squirtle, so let’s name this “Pokémon - Squirtle”.

It also requires a collection, so click Create Collection and let’s name the collection “My Favorite Pokémon”.

Click the orange checkmark button next to the collection name then hit Save.

At this point we’ll have a new request, so let’s build that request.

There are two things we’ll first need to fill out for our first request:

• Request type: GET, POST, PUT, etc - we’ll use GET
• Request URL: The endpoint for your API request - for our request we’ll use https://pokeapi.co/api/v2/pokemon/squirtle/

And once you make sure those are correct, you can simply hit the blue Send button on the right and we’ve successfully made our first request!

We immediately get a few things we can see:

• Body: at the bottom we should now see the response body of the API request. For our Squirtle API, we should have a JSON object with data like abilities, base_experience, and forms.
• Status: on the right, we should see the HTTP status code. “200 Ok” is a good sign and it means it was successful!
• Time: simply how long the request took to finish
• Size: the size in KB (in our example) of the response data

You can also hover over Status, Time, and Size and get a more in depth look at each option.

So we made our first request!

Once thing to notice before we move on is that our request looks like it’s in a browser tab. If we’re done with that particular request, we can close the tab and click Save to make sure all of our changes are there for next time!

Part 3: Creating a collection of requests in Postman for the PokéAPI

Now that we’ve created a request, let’s create a collection of them. Technically we already had to create a new collection for Part 2, but we’ll create a new one to learn how collections themselves work.

At the top left of the UI, click the orange New button again and select Collection.

Similar to a request, it asks for a name so let’s call this “PokéAPI”. Optionally you can add a description, then click Create at the bottom.

On the left, you’ll now see your collection. You can select and expand the folder since we’ll be working with it.

Before we add a request, the PokéAPI has different types of requests, so it makes sense to organize it a little more thoroughly. So let’s click the three dots next to the PokéAPI collection and select Add Folder.

Similar to the others, this asks for a name. Folders are kind of like collections inside of a collection, so you get similar options. Let’s name this one “Pokémon” and click the orange Save button like before.

Now let’s add our requests! First, click the three dots next to the Pokémon folder, similar to how we added a folder to the collection, but this time select Add Request.

Let’s name this request “Pokemon”. While it might be confusing that we have a Pokemon request inside of the Pokémon folder, Pokemon is just one of the endpoints of the Pokémon group.

Now, let’s use the same exact API that we used with our Squirtle request before:

• Request Type: GET
• Request URL: https://pokeapi.co/api/v2/pokemon/squirtle/

And similar to before, when we hit the blue Send button, we should see a successful request!

Now let’s add another request. Follow the same process as before to create a new request under the PokéAPI Pokémon folder and let’s name this request “Abilities”.

If you scroll through the response from the first Squirtle endpoint, you see a lot of other API urls. At the top, we have abilities and we have two different ones — “torrent” and “rain-dish”.

Choose your favorite Squirtle ability and copy the url value into the new Abilities request we just created, I’m going to use rain-dish.

We can leave the Request Type as GET, hit the blue Send button, and we can again see a successful response!

Here we get a lot of information about our Squirtle ability Rain Dish and some of the details come in different languages which is cool!

So now we have a new PokéAPI collection with a Pokémon folder representing the group of Pokémon API endpoints including Pokemon and abilities.

We’re going to stop Part 3 with those 2 requests, but feel free to continue on and add as many of the PokéAPI requests as you’d like!

Part 4: Making POST requests with Postman to translate sentences to sound like Yoda

So far we’ve only made GET requests, but what if we wanted to make a POST request where we need to actually send some data?

For making a POST request, we’re going to use the Yoda Translator API from funtranslations.com. While this API only takes a single parameter, it’s still a good public endpoint we can use to understand the concept.

First, let’s create a new collection with a new request:

• Collection: Fun Translations
• Request: Yoda

This time, instead of a GET request, our request configuration will be:

• Request Type: POST
• Request URL: https://api.funtranslations.com/translate/yoda

Now this time, if we hit the blue Send button, we’ll notice we don’t get a successful 200 response, we get a 400!

We never actually set up any data to be posted to the API and it requires that data, so let’s add it.

Right below the Request URL, click Body. Then instead of none, select raw as the body type. Finally, on the far right of the types, change Text to JSON.

Then, in the space below it, you can add the following:

{
    "text": "Hello, I am learning how to test APIs with Postman!"
}

And now click the blue Send button again and we get a successful response!

We can apply this concept to pretty much any API. Postman doesn’t only permit you to post JSON, it allows you to use the other formats that we see listed in the Body Type section, meaning you have a lot of options depending on what the API you’re using requires.

Part 5: Authenticating requests to the Lord of the Rings API with an API Key

For the rest of the walkthrough, we’re going to use the Lord of the Rings API.

First up, the Lord of the Rings API requires authentication in order to make requests using an API key. So to start, you’ll before we dive in, you’ll need to go create a free account.

https://the-one-api.herokuapp.com/sign-up

Once you sign up and log in, the first thing you’ll see is your API key! Either copy this key down or remember where you can find it for later. If you leave the page, you can always grab it by navigating to Welcome and then Account in the navigation of the API website.

To get started, let’s first create a new collection and request:

• Collection: Lord of the Rings
• Folder: Movie
• Request: All Movies
• Request Type: GET
• Request URL: https://the-one-api.herokuapp.com/v1/movie

Once you’re set with the above, click Send, and you’ll notice immediately it gives a response that says 401 and that it’s unauthenticated.

Because this API requires the API key, this is exactly what we expected. So let’s click on the Authorization tab. We can then select a Type of Bearer Token, and on the right, we can paste in our key that we just set up with the Lord of the Rings API.

And as soon as we hit Send, we now see a successful response!

This worked really great, but what if we have a bunch of requests that use a single key. Do we have to manage that on each request?

Instead of managing it on each individual request, we can manage it on the collection. Let’s first build another request.

Under our Lord of the Rings collection and in the Movie folder, create a new request:

• Request: Quote by Movie ID
• Request Type: GET
• Request URL: https://the-one-api.herokuapp.com/v1/movie/{id}

In this request, let’s use an ID from the response of the first request, I’m going to use 5cd95395de30eff6ebccde5b which is the ID of The Two Towers, so the request URL will look like:

https://the-one-api.herokuapp.com/v1/movie/5cd95395de30eff6ebccde5b

Now, instead of setting our token in the request Authorization, we’re going to leave the type as Inherit auth from parent. Click on the three dots next to the collection and select Edit.

Here, we’re going to do the same exact thing we did with the first request but on the Collection configuration. Select the Authorization tab, under type select Bearer Token, and in the Token field again paste your token.

Finally, click Update and hit the blue Send button again and we can see a successful request!

We can now go back to our All Movies request and update the Authorization to use a Type of Inherit auth from parent and it should still continue to work!

What else can we do with Postman?

While I covered a lot of the basics, there’s quite a lot more you can do with Postman. Here are a few of my favorites.

Environment Variables

If you’re working as a developer on a project, it’s likely that your team uses multiple environments, such as a development and production environment. Instead of creating and maintaining completely separate requests, you can add an environment variable and instead change that variable when switching between environments!

Variables apply to many scenarios, but that’s a common use. Check out Postman’s docs to learn how.

https://learning.postman.com/docs/postman/variables-and-environments/variables/

Import and Export Collections and Data

A great thing about Postman is once you have your requests all organized, you can export them for others to use. This also means that you can import collections from other team members. This makes it much easier to make sure everyone’s using the same collection.

Bonus: you can even store these files in a Git repository, as they’re just JSON.

But keep in mind - if you’re using Authorization on the collection like we went over in this guide, you’ll want to make sure you don’t include that when exporting your collection.

https://learning.postman.com/docs/postman/collections/importing-and-exporting-data/

Automated testing

Once you have a set of requests in a collection and even better, if you’re storing them in Github, you can begin to use those requests as part of a way to manage automated testing of your API.

While there are a few solutions for doing this, Postman includes a Collection runner built right into the app and Newman is a command line tool that lets you run tests right from the terminal.

https://www.postman.com/use-cases/api-testing-automation/

What’s your favorite way to test and play with APIs?

Share with me on Twitter!

QA files are created in the direction of the bug handler to manage these defects confidentially. They serve us as a roadmap, ensuring a clean and efficient QA process and making it easier to have a clean conversation between the fixers and the testers.

But you might be wondering – why do we need QA documentation?

QA testing is essential in IT products today. Tight deadlines, unique skill sets within the organization, and the demand to develop products stress the need for a structured methodology. QA documentation guides testers through levels of clarity and overall coverage.

I've written this article to make your life a bit easier. So here it is, your ultimate guide on how to write software QA documentation that will work.

• Make a Test Plan and a Test Progress Report
• Create Test Cases
• Defect Reports
• Useful Tips for Defect Report Writing
• Submit a Defect Report
• Conclusion

Make a Test Plan and a Test Progress Report

Developing great software requires a thorough and documented approach to testing. Everything begins in the development phase with a complete checkout plan as a template for the entire QA process. It outlines the general requirements, defines the followed route, identifies the necessary assets, and sets a simple timeline for achieving the objectives.

Draw up a roadmap before you start

Before you start implementing your test plan, take some time to think about the big picture. Ask yourself:

What problem does this software solve? As soon as you understand the main purpose of the software, you'll be able to manage the checkout process and identify the features that are most important to your goals.

I promise that once you see that you can do this, you quickly prioritize your efforts. They are based primarily on the importance of the functionality and its impact on the user.

Create a plan

The test plan is the central part of the QA technique. The test plan should contain the following key elements:

• Imaginary test: Clearly identify the expected impact of the payment method. Will it confirm that core functionality is running smoothly, or will it alert you to capability gaps?
• Test method: Outline how the test will be performed. Will you do targeted testing, useless testing, or a mix of the two?
• Resource allocation: Identify the equipment and technology required to perform a complete control. What control framework will you use? Are specific hardware or software configurations required for proper control?
• Timetable and remaining dates: Establish a realistic timetable for the trial. Set clear deadlines to keep the project on track.

Understand the 'why' and 'how'

A well-developed roadmap will ensure that key issues are addressed throughout the improvement approach:

• Acceptance requirements: Clear fail/success criteria should be defined for all control cases. So, criteria allow the customer to understand that the product is high quality and ready for the end-user.
• Resource management: Identify the assets required for the testing. This includes preferred machines, copies of software in various forms, required expertise, and more.
• Team dynamics: Ensure that simple roles and tasks are defined within the test team. Who is responsible for particular test cases? Who documents bugs and who talks to developers?
• Time management: I advise setting realistic checkout times, taking into account project deadlines and the availability of useful help.

The test progress report is another part of the QA documentation, similar to the test plan, but with additional data on current progress. This document allows you and your development team to monitor project progress and identify any organizational issues.

A test plan and a progress report

Create Test Cases

Think of each test case as a detailed recipe for finding potential defects in the functionality of a software program. By following these "recipes" and evaluating the expected and actual results, defects can be accurately identified and addressed before preventive action is taken.

Each test case acts as an independent unit, outlining the steps required to evaluate a particular element of a software program.

Below is a breakdown of the key elements that make up a well-defined test case Here is my step-by-step guide for creating test cases:

• ID: This is an identifier field to help distinguish between test cases and track them easily.
• Priority: This indicates the severity of the test case based on the functionality of the program and its impact on the normal overall performance of the known software program application.
• Test Requirements: These are requirements for testing software successfully, this can include reference documents also.
• Software Module: This shows the feature under testing. It also refers to the software requirements specifications (SRS) document explaining the software feature in detail.
• Test Context: This details the test plan to clarify how the daily tests will be carried out. It also identifies the test data required for a successful case study and includes unique and important statistical information.
• Expected Output: This describes the expected output to be displayed if the test is successful.
• Actual output: This indicates the actual result in the event of failure and shows the developer the errors in the application module of the software program.
• Comment: This is an optional section where the tester can give a description of the observations or add additional records.

All QAs typically include the above elements, but can also be designed specifically for the task selected by the QA group. Also, each control case follows a lifecycle that defines the phases of creation, testing (pass, fail), completion, and so on.

In the next section, we’ll check out another important element of QA documentation: the defect report.

Test cases

Defect Reports

Defect reporting is an important element of QA documentation. Issue tracking is the detailed reporting of sudden problems that arise in a software product. Careful documentation of these issues lays the groundwork for a complex and bug-free final product.

Sounds simple, right? Yes, but only until you start documenting.

A defect report

The bug report consists of the following sections: Identifier, Summary, Description, Steps to Reproduce, Reproducibility, Severity, Priority, Environment, and Attachments.

• Identifier: Each software program problem is assigned a completely unique identifier that acts like a customized nameplate. This makes the QA documentation less complicated to navigate and allows verbal communication between the installer, tester, and project manager (PM).
• Summary: This is an opportunity to provide brief and informative answers to three basic questions: What was the problem? Where did the problem appear? Under what specific conditions did the problem appear?
• Explanation: Examine the failure log in more detail. Summarize the identified action (the result completed) and check it against the planned action (the predicted end result). Including a link to the app requirements of the software program can serve as a useful reference element.
• Reproduction method (STR): This phase should be considered as a step-by-step recipe for reproducing the defect. It should be strict and cover all the steps that caused the problem. Skipping critical steps can make it difficult for you to reproduce the problem and cause delays.
• Reproducibility: In this section, you clarify if the bug appears every time you follow the STR. You should use numbers to show approximate chances, for example, 7 times out of 10.
• Severity: Here you explain how much harm the bug may bring to the project. Essentially, this is a measure of the severity of the technical disruption that a bug will cause to the whole project. Remember that problems that are known to be minor can grow and cause you extreme problems throughout the software.
• Priority: Each error log assigns a problem priority that indicates its urgency. Common priorities are letters (A: highest priority, Z: highest priority), numbers (1: highest priority, 9: highest priority), or descriptive terms (high, medium, low).
• Environment: Specify the gadget or browser model in which the bug appeared. This will help you to put the problem in context and narrow down a valid cause.
• Attachments: If possible, enrich the documentation with screenshots, screen recordings, console log documents, and others. This will help to provide visual documentation of the error.

My structure provides detailed information, so you can empower developers to effectively diagnose, address, and eliminate any software bugs. In this way, leading to more user-friendly and robust products.

Now, in the next section, we'll see some useful tips you can use for defect report writing.

Useful Tips for Defect Report Writing

1. Write a sufficient summary. It does not matter if it is long or short. What matters is that it should be clear.
2. Have a look at the summary and the description. Do they look pretty much the same? You must have forgotten to outline the expected and actual results in the description and to add the link to the requirements.
3. Capture the issue with the help of a screenshot. It may save you and the development team a lot of time. Sometimes one glance at the picture is just enough to understand the situation.
4. Before reporting the issue, try to reproduce it at least 3 times to be sure that it exists.
5. Report the issue ASAP and notify your project manager or product owner if the issue is major.
6. Check for grammar mistakes in your QA documentation so you're not taken down by the grammar police.
7. However comical it sounds, make sure that the issue is not a feature – review the documentation again!
8. Do not miss any important information in your Steps to Reproduce.

Submit a Defect Report

The final and one of the most important elements of QA documentation is the defect report. You may understand it covers the entire lifecycle of a problem, from its initial discovery to its final closure.

Let's now examine the key areas of this process:

a defect report lifecycle

We'll go over the defect report lifestyle piece by piece:

Problem Reporting:

This adventure begins with the careful compilation and submission of a report on the entire program. This serves as a roadmap for developers and provides a clear assessment of the problem.

Triage and tasks:

The task manager or technical lead takes on the role of gatekeeper at this stage. They carefully compare the files. If the file contains enough elements to work with, it is assigned to the developer and repaired. However, if the file is missing essential elements, it may be rejected for further improvement.

Bug fixing:

The assigned developer takes the initiative and works diligently to eliminate the annoying bug.

Verification and completion:

Once the developer claims to have fixed the problem, it's your turn as QA. Carefully verify the fix by retesting the functionality in question. If everything works as it should, you are done.

The documentation has come to a happy end. Ideally, this will happen within a reasonable period of one to two weeks.

Reboot and keep going:

But it is not always that simple. If it is known that bugs are still being made in the validation system, there is no need to despair!

Re-open the bug documentation and send it to the developers for further attention. Sometimes the process of fixing bugs is repetitive and requires patience. But by being careful and effective, you can guarantee that all bug reports will eventually reach their final destination, resulting in a more polished and reliable software application product.

Conclusion

Quality Assurance is a process you simply cannot avoid. Each airplane prior to departure undergoes a technical check. If there is any issue, the aircraft is grounded until the problem is solved. The same goes for any software.

But QA documentation is not always "write and ignore". At some point in the software development lifecycle, QA documentation needs to be continually updated and improved as requirements change, new features are introduced, and feedback is received from deployment and production use.

There are also a growing number of styles that use synthetic intelligence and machine learning to partially automate the creation of QA documentation.

For example, natural language processing (NLP) is used to analyze requirements documents and generate draft control examples. Test bots can use NLP to interpret and routinely execute directed test cases. Predictive evaluation can also be used to identify the most dangerous areas of a software program that require more detailed control.

While these strategies are still new and not mature enough to replace human testers, they can help with growth and augment manual exploration, especially for large and complex builds. By making QA documentation a collaborative and ongoing hobby, your team can deliver better software faster and with fewer defects.

Do you need to improve the quality of your software?

My company KeenEthics provides solid development and quality assurance services. In case you need an estimate for a similar project, feel free to get in touch. If you have enjoyed the article, you should continue with How IT Outsourcing Saves Costs for Your Company and Avoiding Pitfalls in IT Outsourcing: Tips for Minimizing Risks.

Quality Assurance (commonly known as QA) is the means by which a product in development is checked to make sure it works as it’s supposed to. The actual methods used in QA processes vary hugely depending on the size and nature of the product.

For a personal project you will probably just test as you go, asking others to provide feedback at appropriate stages. By contrast, a banking application must have every aspect of every feature exhaustively checked and documented to ensure it is both functional and safe.

Regardless of how formal or detailed a QA process is, its aim is to identify bugs so they can be resolved before the product is released.

Methodologies

Agile

In an Agile approach to development, the aim is that each cycle of work (‘sprint’) produces working software that can be added to and improved upon iteratively. This makes the QA processes an intrinsic part of the development cycle.

By testing software components at each stage of their production you reduce the risk of bugs being present at release.

Terminology

Automation Testing

Testing done with pre-written scripts designed to control the execution of tests.

Black Box

These test do not look inside the system under test, but treat it as ‘closed’ in the same way that the end user will experience it.

Defect

Any deviation from an application’s specifications; often referred to as a “bug”.

Exploratory Testing

An unscripted approach to testing, which relies on the tester’s unique creativity in an effort to find unknown bugs and identify regressions.

Integration Testing

Testing individual components/modules together to ensure they connect and interact well with one another.

Negative Path Testing

A testing scenario designed to produce an error state in a feature/application and verify that the error is handled gracefully. An example of this is inputing a series of numbers in the email field in a user registration form and checking to make sure the registration is not accepted until an actual email address is provided.

Regression Testing

Testing done on a new build to ensure that new functionality has not unintentionally broken previously tested functionality.

Smoke Tests

A minimalistic approach to testing intended to ensure basic functionality is working before more in-depth testing takes place. Typically occurs at the beginning of the testing process.

Test Case

Specified preconditions, steps, and expected results referred to by a QA tester/engineer to determine whether or not a feature performs its task as expected.

White Box

Refers to tests performed at a structural level, within the codebase. Programmers checking that the inputs to and outputs from specific functions or components would be white box testing.

Also known as ‘Glass Box’, ‘Clear Box’, ‘Transparent Box’ because the tester can ‘see inside’ the system under test.

Main categories are

• Unit tests (individual units of code do what they should)
• Integration tests (units/components interact with each other properly)
• Regression tests (re-applying tests at later stages of development to ensure they still work)

There are three main techniques:

• Equivalence partitioning (the tested input values are representative of larger input datasets)
• Boundary Value Analysis (the system is tested with chosen inputs where behaviour and therefore output should change)
• Cause-Effect Graphing (tests are designed from a visualization of the input-output relations)

Other Resources

• How to write QA documentation that actually works
• Test Driven Development
• Unit tests

You’ve built out all your user stories and your app is working. Now’s it’s ready to submit as done, so you can move on with your life.

Not so fast!

You need to give your code a health check first.

A professional singer wouldn’t start singing until she’s checked both her mic and her speakers. You shouldn’t deploy until you’ve checked your front end, back end, and everything in between.

I’m an impatient person, but coding makes me slow down. Being a developer teaches me to think at least twice, ask questions until the code works, and wait a moment before celebrating success.

Iteration is the key because good product is never done. The key is to iterate on the versions you are proud of, and not on those that are far from ready to go live.

So treat this as a final checklist before going live.

1. Be responsive

How does your app behave when you resize the browser window? Where do you have your breakpoints in code? Is it fluid enough to fit all sizes without bigger problems?

There are an endless variety of screen sizes. It’s impossible to have all of the devices within reach but, it’s easy to emulate their behavior.

Spending some time in Code Review Room, I’ve noticed that many people focus on developing for desktops when they should actually be testing their app on mobile devices first.

Browser tools allow us to emulate the display on various screen sizes and orientations. Use them, they are free.

In Chrome, you can go to a debug view by right clicking any element on the page and selecting “inspect element”, then going to mobile view and emulating different devices.

Chrome browser emulation mode

2. Consider special cases and app states

Empty, error, success, waiting, 404 page, or duplicated button clicks while waiting for API response — how does your app react to them? Do you care about these states that are far from ideal situation you coded for? Do you have helpful feedback to your users for when they encounter these? Have you tested for these special cases? Do you listen and respond in your app, or do you do all the talking?

Design, code, and test for all states. Checking user flows can help you a lot to get rid of these easily forsaken points and dead ends. Simply test your work with some users, or at least do it on your own.

Put yourself in users’ shoes by imagining various scenarios that may happen, and remember that this app is completely new for this person.

Try incorrect data inputs, no input at all, misspellings, etc. Be imaginative and try to break your code! Better you do it before your users.

3. Optimize your performance

Google PageSpeed Insights does a great job in telling you what could be done better.

If you want others to be able to read and review your code, don’t minify your JavaScript or CSS — it will make it hard for humans to read. However, you should do it for production code.

For production, you can also use tools such as Grunt to handle and other operations optimizations for you.

By using the tests such as PageSpeed, you can get quick opinion not only on performance, but also on usability issues. Test results provide you with ready suggestions for how to improve your code. Again, you don’t have to accept all, simply choose the suggestions that work for the goals you want to achieve.

UX basic health check with PageSpeed tool

4. Do cross browser testing on every device you have available

Many of us have access to at least two different devices (a computer and a smartphone), and some of us even dual boot different operating systems. Browser emulation has its flaws, so when possible use the native hardware.

You don’t have to write unit tests for a small app showing wiki entries or local weather to check if they work. Test driven development is a great practice, but not the easiest for fresh coders and it may be an excess of form for short code snippets.

What you have to be aware of though is that testing is a part of front end developer’s job, even if there’s a huge team of testers sitting next to you in the same room. Before you assign the ticket to other team member you have to make sure it works. Don’t assume, check.

With code, it either works or it doesn’t. There’s no maybe or I suppose.

Cross browser testing can be time-consuming, but there are plenty of tricks to make it more efficient. For instance, each time you test, try using a different browser.

Since you test it while iterating over the project, you can test your code on various browsers many times during the creation of the app itself. Then, before launching the final version it’s much faster to make a quick browser health check, since majority of problems have probably already been discovered and fixed.

Browser developer tools and extensions allow you also to easily discover accessibility constraints before you push the project live. You can also use BrowserStack, which I’ve found helpful in doing cross-browser testing.

Accessibility Audits in Chrome

I recently a nice accessibility checklist. If you want to dig deeper in the topic you may also like to check your apps with ARIA techniques, articles on designing for keyboard, or look through Simply Accessible archives.

5. Keep your head on

Source: giphy.com

Double check the head section of your HTML, and make sure you have meta descriptions, a viewport set up for mobile, a title tag, and a favicon. Keep at least the basic meta tags, such as description and author. SEO rules change quickly, but an informative description can increase your likelihood of being clicked on a crowded search result page.

If you’re serious about sharing your work, make it easy for others to collaborate. Keep your README.md file concise and explanatory. It’s how most people will view your project on GitHub, so don’t omit this file in your repo.

If you code some small projects on CodePen, go to settings section and add a basic description of your pen and tags. This will allow your work to be easier discovered and understood by others.

Provide some small info about your pens.

Make sure you import assets and libraries appropriately. If you want to move your project from CodePen to another server, make sure that the external libraries, frameworks, and stylesheets you used in your pen are included.

If you want just a copy for your Github and it’s a small project, you can simply export your pen to gist. To do this, use the export button in the bottom-right corner of Editor View.

6. Code optimization

Keep DRY (don’t repeat yourself). Once done, have a look at the code once again. Maybe there are snippets which you repeat and they could be replaced by one smart function. Analyze your code once again and look what could be written better. The more you code, the wiser in DRY you become. It’s said to be a good learning code practice to come back to your own code after some time and refactor it. Give it a try.

Before finishing the project clean your toys.

All console logs are useful for debugging during creation but unwelcome for production code.

Make comments concise and clear for others reading your code, and preferably in English, unless everyone else on your team speaks the same language.

Make sure there aren’t any console errors, and that all your assets load properly (for that check Network tab in your browser’s developer tools).

You may want to use code validators for JavaScript, HTML, and CSS. Like with PageSpeed the key is to understand what is worth optimizing.

7. User Experience

Quick UX health check of your project should include the basics like:

• Goals. Are the users able to solve their problems? Are their expectations met? Do they get what they came for to your app/website? What would a user tell the app is about seeing it just for a moment?
• Dead-ends. Have you checked all possible paths your users can take? Are you helpful? Do you provide feedback just in time a user needs it?
• Visual hierarchy. Is the hierarchy kept? Do you lead users eye? Is your call-to-action visible? Do you have too many items to focus on that fight for being the primary element on a given screen?
• Line width. Is your text easy to scan? Your lines should be no wider than 80 characters. And make sure your lines aren’t too narrow with too much padding.
• Readability. Is your text readable? Are the images of the right size? Is there contrast between elements appropriate?
• Affordability. Do your buttons look like buttons? Do your links behave like links? Will a user know that an element is clickable or tappable? Does your cursor turn into a finger pointer where appropriate?
• Consistency. Are you consistent in your app? Or do you use 5 different colors to mark the same thing or do you have it organized?
• Microinteractions. Do you help your users to notice when the elements are hovered in desktop view? How do you mark interactions? Do you respond to what a user does in your app?
• Sunlight check. How does your app behave outside in sunlight? Is everything readable?
• Screenreader test. Have you tried using your app with a screenreader? Is it possible to use it fully being directed just with Voice Over or another screenreader tool?
• Proof-read your copy. Have you got rid of lorem ipsum texts? Are your alerts, warnings, etc. written in a human language, or do they still read like a developer in a hurry wrote them?

8. Code Review on Gitter

When you are ready with the previous points go to the Code Review room. Campers are lucky to belong to the community where everybody understands that you are fresh in coding. It’s OK if you make mistakes. We all learn by practicing, and gradually improve our code.

Campers have various prior coding background, and are all at different points in Free Code Camp’s program. So finding help is quite easy.

Don’t ask too early. Ask for feedback later when your app has started to take on its own character and shape. Try to discover the answer first. Google and Stack Overflow are your first stops. Sure, if you get stuck with some problem jump in to the appropriate room and ask! That’s the part of Free Code Camp magic, isn’t it?

Be precise about what you’re looking for. Asking precise questions leads you to better answers. Asking a general question like “Here’s my code. What do you think?” will get you a general answer. This can bring a lot of new ideas to light, and a fresh look that can be inspiring. However, a lot of design suggestions are pretty subjective (based on personal taste, and gut reaction after a few seconds), so don’t jump to the conclusion that you must refactor all your code just because one person said so. Ask for justification if you don’t understand what the other person meant. Repeat your question to get feedback from others, and sleep on the suggestions if you are not sure if the change is right for your project.

I love getting constructive feedback. It’s better to get a list of suggestions than bunch of praise. Kind words are sometimes needed, but informative comments full of empathy are better for making progress. As you progress, your motivation will become more intrinsic.

Bigger projects, shorter lists

Sitemaps, unit tests, functional tests, caching, analytics, appropriate file directories, checking if assets aren’t missing, print version css, SEO optimization… this list could go on for quite a while for sure.

But the more you code, the shorter the list seems to appear, because you will simply code better and internalize many of these considerations.

I am a web developer in training. I am a Free Code Camper. I publish on Medium and tweet about UX and startups. I love useful solutions and friendly collaboration.