Author Archives: Google Testing Bloggers

Include Only Relevant Details In Tests

This article was adapted from a Google Testing on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Dagang Wei

What problem in the code below makes the test hard to follow?

def test_get_balance(self):

settings = BankSettings(FDIC_INSURED, REGULATED, US_BASED)

account = Account(settings, ID, BALANCE, ADDRESS, NAME, EMAIL, PHONE)

self.assertEqual(account.GetBalance(), BALANCE)

The problem is that there is a lot of noise in the account creation code, which makes it hard to tell which details are relevant to the assert statement.

But going from one extreme to the other can also make the test hard to follow:

def test_get_balance(self):

account = _create_account()

self.assertEqual(account.GetBalance(), BALANCE)

Now the problem is that critical details are hidden in the _create_account() helper function, so it’s not obvious where the BALANCE field comes from. In order to understand the test, you need to switch context by diving into the helper function.

A good test should include only details relevant to the test, while hiding noise:

def test_get_balance():

account = _create_account(BALANCE)

self.assertEqual(account.GetBalance(), BALANCE)

By following this advice, it should be easy to see the flow of data throughout a test. For example:

Bad (flow of data is hidden):

Good (flow of data is clear):

def test_bank_account_overdraw_fails(self):

account = _create_account()

outcome = _overdraw(account)

self._assert_withdraw_failed(

outcome, account)

def _create_account():

settings = BankSettings(...)

return Account(settings, BALANCE, ...)

def _overdraw(account):

# Boilerplate code

...

return account.Withdraw(BALANCE + 1)

def _assert_withdraw_failed(

self, outcome, account):

self.assertEqual(outcome, FAILED)

self.assertEqual(

account.GetBalance(), BALANCE)

def test_bank_account_overdraw_fails(self):

account = _create_account(BALANCE)

outcome = _withdraw(account, BALANCE + 1)

self.assertEqual(outcome, FAILED)

self.assertEqual(

account.GetBalance(), BALANCE)

def _create_account(balance):

settings = BankSettings(...)

return Account(settings, balance, ...)

def _withdraw(account, amount):

# Boilerplate code

...

return account.Withdraw(amount)

Source: Google Testing Blog

Simplify Your Control Flows

This is another post in our Code Health series. A version of this post originally appeared in Google bathrooms worldwide as a Google Testing on the Toilet episode. You can download a printer-friendly version to display in your office.

By Jeff Hoy

When adding loops and conditionals, even simple code can become difficult to understand.
Consider this change:

if (commode.HasPreferredCustomer()) {	if (commode.HasPreferredCustomer()) {
commode.WarmSeat();	commode.WarmSeat();
	} else if (commode.CustomerOnPhone()) {
	commode.ChillSeat();
}	}

While the above change may seem simple, even adding a single else statement can make the code harder to follow since the complexity of code grows quickly with its size. Below we see the code surrounding the above snippet; the control flow on the right illustrates how much a reader needs to retain:

while (commode.StillOccupied()) {

if (commode.HasPreferredCustomer()) {

commode.WarmSeat();

} else if (commode.CustomerOnPhone()) {

commode.ChillSeat();

}

if (commode.ContainsKale()) {

commode.PrintHealthCertificate();

break;

}

Code Control Flow with 5 structures and 9 edges:

challenging for a reader to retain in memory.

In order to fully understand the code, the reader needs to keep the entire control flow in their head. However, the retention capacity of working memory is limited (source) Code path complexity will also challenge the reader, and can be measured using cyclomatic complexity.

To reduce cognitive overhead of complex code, push implementation logic down into functions and methods. For example, if the if/else structure in the above code is moved into an AdjustSeatTemp() method, the reviewer can review the two blocks independently, each having a much simpler control graph:

while (commode.StillOccupied()) {

commode.AdjustSeatTemp();

if (commode.ContainsKale()) {

commode.PrintHealthCertificate();

break;

}

3 control structures and 5 edges: easier to remember

Commode::AdjustSeatTemp()

with 2 structures and 4 edges

Avoiding complexity makes code easier to follow. In addition, code reviewers are more likely to identify logic errors, and maintainers are less likely to introduce complex code.

Source: Google Testing Blog

Improve Readability With Positive Booleans

By Max Kanat-Alexander

Reading healthy code should be as easy as reading a book in your native language. You shouldn’t have to stop and puzzle over what a line of code is doing. One small trick that can assist with this is to make boolean checks about something positive rather than about something negative.

Here’s an extreme example:

if not nodisable_kryponite_shield:

devise_clever_escape_plan()

else:

engage_in_epic_battle()

What does that code do? Sure, you can figure it out, but healthy code is not a puzzle, it’s a simple communication. Let’s look at two principles we can use to simplify this code.

1. Name your flags and variables in such a way that they represent the positive check you wish to make (the presence of something, something being enabled, something being true) rather than the negative check you wish to make (the absence of something, something being disabled, something being false).

if not enable_kryponite_shield:

devise_clever_escape_plan()

else:

engage_in_epic_battle()

That is already easier to read and understand than the first example.

2. If your conditional looks like “if not … else …” then reverse it to put the positive case first.

if enable_kryponite_shield:

engage_in_epic_battle()

else:

devise_clever_escape_plan()

Now the intention of the code is immediately obvious.

There are many other contexts in which this gives improvements to readability. For example, the command foo --disable_feature=False is harder to read and think about than
foo --enable_feature=True, particularly when you change the default to enable the feature.

There are some exceptions (for example, in Python, if foo is not None could be considered a “positive check” even though it has a “not” in it), but in general checking the presence or absence of a positive is simpler for readers to understand than checking the presence or absence of a negative.

Source: Google Testing Blog

Shell Scripts: Stay Small & Simple

A version of this post originally appeared in Google bathrooms worldwide as a Google Testing on the Toilet episode. You can download a printer-friendly version to display in your office.

By David Mandelberg

Shell scripts (including Bash scripts) can be convenient for automating simple command line procedures, and they are often better than keeping complicated commands in a single developer's history. However, shell scripts can be hard to understand and maintain, and are typically not as well-supported as other programming languages. Shell scripts have less support for unit testing, and there is likely a lower chance that somebody reading one will be experienced with the language.

Python, Go, or other general-purpose languages are often better choices than shell. Shell is convenient for some simple use cases, and the Google shell style guide can help with writing better shell scripts. But it is difficult, even for experienced shell scripters, to mitigate the risks of its many surprising behaviors. So whenever possible, use shell scripts only for small, simple use cases, or avoid shell entirely.

Here are some examples of mistakes that are far too easy to make when writing a shell script (see Bash Pitfalls for many more):

Forgetting to quote something can have surprising results, due to shell's complicated evaluation rules. E.g., even if a wildcard is properly quoted, it can still be unexpectedly expanded elsewhere:

$ msg='Is using bash a pro? Or a con?'

$ echo $msg # Note that there's a subdirectory called 'proc' in the current directory.

Is using bash a proc Or a con? # ? was unexpectedly treated as a wildcard.

Many things that would be function arguments in other languages are command line arguments in shell. Command line arguments are world-readable, so they can leak secrets:

$ curl -H "Authorization: Bearer ${SECRET}" "$URL" &

$ ps aux # The current list of processes shows the secret.

By default, the shell ignores all errors from commands, which can cause severe bugs if code assumes that earlier commands succeeded. The command set -e can appear to force termination at the first error, but its behavior is inconsistent. For example, set -e does not affect some commands in pipelines (like false in false | cat), nor will it affect some command substitutions (such as the false in export FOO="$(false)"). Even worse, its behavior inside a function depends on how that function is called.
Many things run in subshells, which can (often unexpectedly) hide changes to variables from the main shell. It can also make manual error handling harder, compounding the issue above:

$ run_or_exit() { "$@" || exit $?; } # Executes the arguments then exits on failure.

$ foo="$(run_or_exit false)" # Exits the $() subshell, but the script continues.

Source: Google Testing Blog

The Secret to Great Code Reviews: Respect Reviewers’ Comments

By Marius Latinis

You prepared a code change and asked for a review. A reviewer left a comment you disagree with. Are you going to reply that you will not address the comment?

When addressing comments for your code reviewed by colleagues, find a solution that makes both you and the reviewer happy. The fact that a reviewer left a comment suggests you may be able to improve the code further. Here are two effective ways to respond:

When it’s easy for you to make an improvement, update the code. Improved code benefits future readers and maintainers. You will also avoid a potentially long and emotional debate with a reviewer.

If the comment is unclear, ask the reviewer to explain. To facilitate the process, talk directly with the reviewer through chat, or in person.

Let’s demonstrate with an example code review scenario:

You prepare a code change that modifies the following function:

3 // Return the post with the most upvotes.	3 // Return the post with the most upvotes.
	4 // Restrict to English if englishOnly = true.
4 Post findMostUpvotedPost(	5 Post findMostUpvotedPost(
5 List<Post> posts) {	6 List<Post> posts,
	7 boolean englishOnly) {
6 ...	8 ... // Old and new logic mixed together.
7 }	9 }

The code reviewer leaves the following comment:
alertreviewer
11:51 AM
The new function signature is too complex. Can we keep the signature unchanged?

Reply

You disagree with the comment that one additional parameter makes the signature too complex. Nevertheless, do not reject the suggestion outright.

There is another issue that might have prompted the comment: it is not the responsibility of this function to check the post’s language (https://en.wikipedia.org/wiki/Single-responsibility_principle).

You rewrite your code to address the reviewer’s comment:
ImmutableList<Post> englishPosts = selectEnglishPosts(posts); // Your new logic.
Post mostUpvotedEnglishPost = findMostUpvotedPost(englishPosts); // No change needed.

Now the code is improved, and both you and the reviewer are happy.

Source: Google Testing Blog

Communicate Design Tradeoffs Visually

A version of this post originally appeared in Google bathrooms worldwide as a Google Testing on the Toilet episode. You can download a printer-friendly version to display in your office.

By Tim Lyakhovetskiy

A goal of any written design or project proposal is to present and evaluate alternatives. However, documents that include multiple solutions can be difficult to read when the qualities of each solution are not clearly expressed.

A common approach to simplifying proposals is to use “pros and cons” for each alternative, but this leads to biased writing since the pros and cons may be weighed differently depending on the reader’s priorities.

In this example, can you quickly tell how this option would measure up against others?

Option 1 - Optimize Shoelace Untangling Wizard in ShoeApp UI

Pros

Shoelace Untangling Wizard UI will use 10% less CPU
Less than one quarter to implement
Users will see 100ms less UI lag

Cons

Security risk (shoelace colors exposed) until ShoeAppBackend team fixes lacing API
ShoeAppBackend will be blocked for 3 months
User documentation for Shoelace Untangling Wizard UI has to change

This format requires the reader to remember many details in order to evaluate which option they prefer. Instead, express tradeoffs using impact on qualities. There are many common quality attributes including Performance, Security, Maintainability, Usability, Testability, Scalability, and Cost.

Use colors and symbols in a table (➖ negative, ～ somewhat negative, ➕ positive) to make it easy for readers to parse your ideas. The symbols are needed for accessibility, e.g. color-blindness and screen readers.

Option 1 - Optimize Shoelace Untangling Wizard in ShoeApp UI

Usability	➕ Users will see 100ms less UI lag
Usability	～ User documentation for Shoelace Untangling Wizard UI has to change
Security	➖ Security risk (shoelace colors exposed) until ShoeAppBackend fixes lacing API
Partner impact	➖ ShoeAppBackend will be blocked for 3 months
Performance	➕ Shoelace Untangling Wizard UI will use 10% less CPU
Schedule/Cost	➕ Less than one quarter to implement

Notice that the content uses approximately the same space but communicates more visually. The benefit is even greater when there are many alternatives/attributes, as it’s possible to evaluate the whole option at a glance.

Source: Google Testing Blog

Else Nuances

By Sam Lee and Stan Chan

If your function exits early in an if statement, using or not using an else clause is equivalent in terms of behavior. However, the proper use of else clauses and guard clauses (lack of else) can help emphasize the intent of the code to the reader.

Consider the following guidelines to help you structure your functions:

Use a guard clause to handle special cases upfront, so that the rest of the code can focus on the core logic. A guard clause checks a criterion and fails fast or returns early if it is not met, which reduces nesting (see the Reduce Nesting article).

def parse_path(path: str) -> Path:

if not path:

raise ValueError(“path is empty.”)

else:

# Nested logic here.

...

def parse_path(path: str) -> Path:

if not path:

raise ValueError(“path is empty.”)

# No nesting needed for the valid case.

...

Use else if it is part of the core responsibility. Prefer to keep related conditional logic syntactically grouped together in the same if...else structure if each branch is relevant to the core responsibility of the function. Grouping logic in this way emphasizes the complementary nature of each condition. The complementary nature is emphasized explicitly by the else statement, instead of being inferred and relying on the resulting behavior of the prior return statement.

def get_favicon(self) -> Icon:

if self.user.id is None:

return Icon.SIGNED_OUT

if self.browser.incognito: return Icon.INCOGNITO

if not self.new_inbox_items:

return Icon.EMPTY;

return Icon.HAS_ITEMS

def get_favicon(self) -> Icon:

if self.user.id is None:

return Icon.SIGNED_OUT

elif self.browser.incognito:

return Icon.INCOGNITO

elif not self.new_inbox_items:

return Icon.EMPTY

else:

return Icon.HAS_ITEMS

# No trailing return is needed or allowed.

When it’s idiomatic, use a switch (or similar) statement instead of if...else statements. (switch/when in Go/Kotlin can accept boolean conditions like if...else.)

Not all scenarios will be clear-cut for which pattern to use; use your best judgment to choose between these two styles. A good rule of thumb is use a guard if it's a special case, use else if its core logic. Following these guidelines can improve code understandability by emphasizing the connections between different logical branches.

Source: Google Testing Blog

Use Abstraction to Improve Function Readability

By Palak Bansal and Mark Manley

Which version of the createPizza function below is easier to understand?

func createPizza(order *Order) *Pizza {

pizza := &Pizza{Base: order.Size,

Sauce: order.Sauce,

Cheese: “Mozzarella”}

if order.kind == “Veg” {

pizza.Toppings = vegToppings

} else if order.kind == “Meat” {

pizza.Toppings = meatToppings

}

oven := oven.New()

if oven.Temp != cookingTemp {

for (oven.Temp < cookingTemp) {

time.Sleep(checkOvenInterval)

oven.Temp = getOvenTemp(oven)

}

if !pizza.Baked {

oven.Insert(pizza)

time.Sleep(cookTime)

oven.Remove(pizza)

pizza.Baked = true

}

box := box.New()

pizza.Boxed = box.PutIn(pizza)

pizza.Sliced = box.SlicePizza(order.Size)

pizza.Ready = box.Close()

return pizza

}

func createPizza(order *Order) *Pizza {

pizza := prepare(order)

bake(pizza)

box(pizza)

return pizza

}

func prepare(order *Order) *Pizza {

pizza := &Pizza{Base: order.Size,

Sauce: order.Sauce,

Cheese: “Mozzarella”}

addToppings(pizza, order.kind)

return pizza

}

func addToppings(pizza *Pizza, kind string) {

if kind == “Veg” {

pizza.Toppings = vegToppings

} else if kind == “Meat” {

pizza.Toppings = meatToppings

}

func bake(pizza *Pizza) {

oven := oven.New()

heatOven(oven)

bakePizza(pizza, oven)

}

func heatOven(oven *Oven) { … }

func bakePizza(pizza *Pizza, oven *Oven) { … }

func box(pizza *Pizza) { … }

You probably said the right-hand side is easier, but why? The left side mixes together several levels of abstraction: low-level implementation details (e.g., how to heat the oven), intermediate-level functions (e.g., how to bake pizza), and high-level abstractions (e.g., preparing, baking, and boxing the pizza).

The right side is easier to follow because the functions have a consistent level of abstraction, providing a top-down narrative of the code’s logic. createPizza is a high-level function that delegates the preparing, baking, and boxing steps to lower-level specialized functions with intuitive names. Those functions, in turn, delegate to their own lower-level specialized functions (e.g., heatOven) until they reach a function that handles implementation details without needing to call other functions.

Avoid mixing different abstraction layers into a single function. Nest functions at equal abstraction levels to provide a narrative. This self-documenting style is simpler to follow, debug, and reuse.

You can learn more about this topic in the book Clean Code by Robert C. Martin.

Source: Google Testing Blog

Better Feedback Makes for Faster Reviews

Testing on the Toilet Presents...

Healthy Code on the Commode

Better Feedback Makes for Faster Reviews

by Felipe Sodré and Adam Bender

Have you ever received a code review with a comment like this?

server_is_alive = InitializeServer()

Comment:

This doesn’t make any sense. Why don't you use InitializeServerWithAFewExtraSteps() instead?

If so, it probably left you scratching your head. Why is the reviewer asking this question? Are they testing you? Did you make a big mistake? The problem is the comment is vague (and maybe even a bit rude). It also leaves out important context as to what the reviewer is thinking, making it difficult to respond to. Here are a few simple ways to ensure your review comments are effective, helpful, and clear.

Be kind! People are more receptive to feedback if you assume competence and treat them with respect.
Focus your comments on the code, not the author. Avoid statements with the word ‘you’ which can give the impression that you are judging the person and not the artifact.
Explain why you are making the comment. You may be aware of alternatives that are not obvious to the author, or they may be aware of additional constraints.
Express the tradeoffs your suggestion entails and take a pragmatic approach to working with the author to achieve the right balance.
Approach your role as a guide, not a test grader. Balance giving direct guidance with leaving some degrees of freedom for the author.
Consider marking low priority comments with severity like Nit, Optional, or FYI to help the author prioritize the important ones.

Some comments can be difficult to express concisely. If you have a rewrite in mind, like a subtle API usage or structural change (e.g., split this big change into smaller changes), consider providing an example. If you find you are stuck after more than two rounds of feedback, consider moving to a more direct communication channel like chat or live call to discuss next steps.

When done well, comments can make code reviews more efficient and collaborative:

server_is_alive = InitializeServer()

Comment:

InitializeServerWithAFewExtraSteps() seems to achieve the same result but with built-in logging and auditing (see http://short_link_here). Would that be a better option here?

The goal of reviews of any kind is to get the best possible outcome for you and your team. Software Engineering is a team effort, and by helping each other more effectively you will deliver better, together!

References: Code Health: Respectful Reviews == Useful Reviews, Google's guide on Code Review Comments

More information, discussion, and archives: testing.googleblog.com

Attribution–ShareAlike 4.0 License (http://creativecommons.org/licenses/by-sa/4.0/).

Source: Google Testing Blog

Code Health: Now You’re Thinking With Functions

This is another post in our Code Health series. A version of this post originally appeared in Google bathrooms worldwide as a Google Testing on the Toilet episode. You can download a printer-friendly version to display in your office.

by Cathal Weakliam

Loops are the standard way to process collections like arrays and lists. However, some loops implement the same patterns repeatedly, leading to duplicate code. Higher-order functions—functions that use other functions as inputs or outputs—can reduce duplication by providing a simpler way to express common operations with collections.

Consider these two loops in JavaScript that decide if every object in an array meets a condition:

let everyRequestValid = true;
for (const request of requests) {
  if (!isValid(request)) {
    everyRequestValid = false;
    break;
  }
}

if (everyRequestValid) {
  // do something
}

let everyUserEligible = true;
for (const user of users) {
  if (!isEligible(user)) {
    everyUserEligible = false;
    break;
  }
}

if (everyUserEligible) {
  // do something
}

The high similarity between the two loops violates the Don’t Repeat Yourself principle and creates an unnecessary burden on readers and maintainers of the code.

To reduce the maintenance burden, use the every method to replace each loop with a single expression. (In other languages every may have a different name, like all or allMatch).

if (requests.every(isValid)) {
  // do something
}

if (users.every(isEligible)) {
  // do something
}

Processing collections with higher-order functions has several benefits:

It significantly reduces duplication by abstracting away the common looping code.
The resulting code is much shorter and simpler, with less opportunity for bugs.
A reader can quickly see the intent of the code as it is not obscured behind low-level control flow.

Two other common higher-order functions are map (apply a function to each element of a collection) and filter (select the elements of a collection that pass a predicate). While the exact syntax varies by language, here’s how they look in JavaScript (using an anonymous function as the argument):

// Double each value in `ints`
const doubled = ints.map(n => n * 2);

// Get only the even values in `ints`
const evens = ints.filter(n => n % 2 === 0);

Just don’t overdo it! Don’t rewrite a loop with functions if it makes it harder to understand, or if it would be considered unidiomatic in your language (for example, in Python, list comprehensions are equivalent to map and filter but are usually preferred).

googblogs.com

All Google blogs and Press in one site

Author Archives: Google Testing Bloggers

Include Only Relevant Details In Tests

Source: Google Testing Blog

Simplify Your Control Flows

Source: Google Testing Blog

Improve Readability With Positive Booleans

Source: Google Testing Blog

Shell Scripts: Stay Small & Simple

Source: Google Testing Blog

The Secret to Great Code Reviews: Respect Reviewers’ Comments

Source: Google Testing Blog

Communicate Design Tradeoffs Visually

Source: Google Testing Blog

Else Nuances

Source: Google Testing Blog

Use Abstraction to Improve Function Readability

Source: Google Testing Blog

Better Feedback Makes for Faster Reviews

Source: Google Testing Blog

Code Health: Now You’re Thinking With Functions

Source: Google Testing Blog