Notes from David Bryant Copeland’s “Build Awesome Command-Line Applications in Ruby 2”

The experience of writing and running automated checks, as well as building some personal apps that run on the terminal, in recent years, has given me a keen sense of appreciation on how effective command-line applications can be as tools. I’ve grown fond of quick programming experiments (scraping data, playing with Excel files, among others), which are relatively easy to write, powerful, dependable, and maintainable. Tons of libraries online help interface well with the myriad of programs in our desktop or out in the web.

Choosing to read “Build Awesome Command-Line Applications in Ruby 2” is choosing to go on an adventure about writing better CLI apps, finding out how options are designed and built, understanding how they are configured and distributed, and learning how to actually test them.

Some notes from the book:

  • Graphical user interfaces (GUIs) are great for a lot of things; they are typically much kinder to newcomers than the stark glow of a cold, blinking cursor. This comes at a price: you can get only so proficient at a GUI before you have to learn its esoteric keyboard shortcuts. Even then, you will hit the limits of productivity and efficiency. GUIs are notoriously hard to script and automate, and when you can, your script tends not to be very portable.
  • An awesome command-line app has the following characteristics:
    • Easy to use. The command-line can be an unforgiving place to be, so the easier an app is to use, the better.
    • Helpful. Being easy to use isn’t enough; the user will need clear direction on how to use an app and how to fix things they might’ve done wrong.
    • Plays well with others. The more an app can interoperate with other apps and systems, the more useful it will be, and the fewer special customizations that will be needed.
    • Has sensible defaults but is configurable. Users appreciate apps that have a clear goal and opinion on how to do something. Apps that try to be all things to all people are confusing and difficult to master. Awesome apps, however, allow advanced users to tinker under the hood and use the app in ways not imagined by the author. Striking this balance is important.
    • Installs painlessly. Apps that can be installed with one command, on any environment, are more likely to be used.
    • Fails gracefully. Users will misuse apps, trying to make them do things they weren’t designed to do, in environments where they were never designed to run. Awesome apps take this in stride and give useful error messages without being destructive. This is because they’re developed with a comprehensive test suite.
    • Gets new features and bug fixes easily. Awesome command-line apps aren’t awesome just to use; they are awesome to hack on. An awesome app’s internal structure is geared around quickly fixing bugs and easily adding new features.
    • Delights users. Not all command-line apps have to output monochrome text. Color, formatting, and interactive input all have their place and can greatly contribute to the user experience of an awesome command-line app.
  • Three guiding principles for designing command-line applications:
    • Make common tasks easy to accomplish
    • Make uncommon tasks possible (but not easy)
    • Make default behavior nondestructive
  • Options come in two-forms: short and long. Short-form options allow frequent users who use the app on the command line to quickly specify things without a lot of typing. Long-form options allow maintainers of systems that use our app to easily understand what the options do without having to go to the documentation. The existence of a short-form option signals to the user that that option is common and encouraged. The absence of a short-form option signals the opposite— that using it is unusual and possibly dangerous. You might think that unusual or dangerous options should simply be omitted, but we want our application to be as flexible as is reasonable. We want to guide our users to do things safely and correctly, but we also want to respect that they know what they’re doing if they want to do something unusual or dangerous.
  • Thinking about which behavior of an app is destructive is a great way to differentiate the common things from the uncommon things and thus drive some of your design decisions. Any feature that does something destructive shouldn’t be a feature we make easy to use, but we should make it possible.
  • The future of development won’t just be manipulating buttons and toolbars and dragging and dropping icons to create code; the efficiency and productivity inherent to a command-line interface will always have a place in a good developer’s tool chest.
Advertisements

The Harajuku Moment

On a chapter from Timothy Ferriss‘s book titled “The 4-Hour Body“, he talks about something significant called the Harajuku moment, described as:

.. an epiphany that turns a nice-to-have into a must-have.

The expression actually came from a realization Chad Fowler (programmer, writer, co-organizer of RubyConf and RailsConf) had in Harajuku with friends some time in the past, while window shopping and lamenting how unfashionable he was. He noticed the tone of helplessness in his own words as he talked about his obesity, and felt angry at himself for being an idiot who went with the flow, making excuses, for many years.

After that defining moment, he turned things around and lost nearly a 100 pounds.

Two years in a row of annual physical exams (2015-2016), I was told that I have hypertension. The previous years I also felt that I tire quickly, becoming more so as the days went by. I’m just over 30, skinny, and believed that I should still be in my prime but was not. I wondered why things turned out the way they did, and eventually recognized that existing habits did not help me become the healthy person I thought I was.

I’m now performing weight-lifts and body-weight exercises 4 times a week, and is in my best shape in the past 10 years or so. What’s interesting is that making the change was actually fun and somewhat easy, very unlike the grueling and exasperating experience I initially thought it would be. I plan to keep things up, gaining as much strength as I can and keeping body fat percentage minimal.

What the Harajuku moment tells us is that, often, on most days, we have insufficient reason to take action. We only have nice-to-haves. We tell ourselves it would be nice to get fit, go on a date with that someone we really like, have a well refactored code, travel internationally, or learn a new skill. But the nice-to-haves do not give us enough pain to move forward. That’s why we sometimes feel we’re stuck in a rut.

Our nice-to-haves must first turn to must-haves before we can take advice and act.

Five People and Their Thoughts (Part 6)

Some engaging articles I’d like to share today:

  • The Failures of ‘Intro to TDD’ (by Justin Searls, about classic test-driven development, code katas, what TDD’s primary benefit actually is, mocks, and discovery testing)
  • Branching is Easy. So? Git-flow Is Not Agile (by Camille Fournier, on Git, tooling, teams, developing software with agility, how easy it is to create feature branches with Git, and some reasons why you don’t need it)
  • What’s Wrong With Estimates? (by Yorgos Saslis, about estimates, why we are being asked to provide estimates, and the pitfalls of the ways we are using them)
  • A New Social Contract for Open Source (by Eran Hammer, on open-source, free code but paid time, sponsorship, making clear rules and specifying benefits, and sustainability)
  • Introducing Example Mapping (by Matt Wynne, about conversations to clarify and confirm acceptance criteria, feedback, colored index cards, and the benefits of writing examples when exploring a problem domain)

A Design Problem

This weekend, while in the middle of a deep dive into the practice of discovery testing on a personal project, I realised that there are different ways of building software from the ground up. That’s actually obvious because there are various programming languages and there are tons of frameworks for quickly constructing apps and sites. It’s literally never been easier to write software from scratch. But simple to start doesn’t mean that what we create turns out to be something that’s easy to maintain or extend, even if the team decides to write more tests or use more tools to monitor the sanity of the codebase. Even if user stories are clear and there’s enough capacity for testing, it can still be difficult to deliver changes without a hitch and on schedule, when the code makes it hard to do so.

For many testers and product owners who have never before looked at the code that runs the apps they test, it may be tough to see how simple feature requests take too long. It can be mind-boggling why bugs continue to creep in. We tend to just accept things as is. Finding out why is one reason I learned how to read and write code myself, besides the desire to have better communication with the devs I work with and having the ability to write my own tools to augment how I test. And after having been writing test code for a number of years now I can say that translating ideas into new code can be easy, but revising existing code to accommodate new business rules is often  troublesome. That means, at least for me, that I have a problem about the way I am writing code for the long haul, even if my app is working at present. I can imagine other programmers having the same predicament.

I now understand that writing long-term, maintainable, software is essentially a design problem. And it seems that a lot of us needs to up our skills in that area.

Bumping Into Discovery Testing

Until recently, what I mostly knew about test-driven development was the concept of red-green-refactor, unit testing application code while building them from the bottom-up. Likewise, I also thought that mocking was only all about mocks, fakes, stubs, and spies, tools that assist us in faking integrations so we can focus on what we really need to test. Apparently there is so much more to TDD and mocks that many programmers do not put into use.

Justin Searls calls it discovery testing. It’s a practice that’s attempts to help us build carefully-designed features with focus, confidence, and mindfulness, in a top-down approach. It breaks feature stories down into smaller problems right from the very beginning and forces programmers to slow down a little bit, enough for them to be more thoughtful about the high-level design. It uses test doubles to guide the design, which shapes up a source tree of collaborators and logical leaf nodes as development go. It favors rewrites over refactors, and helps us become aware of nasty redundant coverage with our tests.

And it categorizes TDD as a soft skill, rather than a technical skill.

He talks about it in more depth in a series of videos, building Conway’s Game of Life (in Java) as a coding exercise. He’s also talked about how we are often using mocks the wrong way, and shared insight on how we can write programs better.

Discover testing is fascinating, and has a lot of great points going for it. I feel that it takes the concept of red-green-refactor further and drives long-term maintainable software right from the start. I want to be good at it eventually, and I know I’d initially have to practice it long enough to see how much actual impact it has.

Favorite Talks from Agile Testing Days 2017

There are two things that’s wonderful from last year’s Agile Testing Days conference talks: content focusing on other valuable stuff for testers and teams (not automation), and having as many women speakers as there are men. I hope they continue on with that trend.

Here’s a list of my favourite talks from said conference (enjoy!):

  • How To Tell People They Failed and Make Them Feel Great (by Liz Keogh, about Cynefin, our innate dislike of uncertainty and love of making things predictable, putting safety nets and allowing for failure, learning reviews, letting people change themselves, building robust probes, and making it a habit to come from a place of care)
  • Pivotal Moments (by Janet Gregory, on living in a dairy farm, volunteering, traveling, toastmasters, Lisa Crispin, Mary Poppindieck and going on adventures, sharing failures and taking help, and reflecting on pivotal moments)
  • Owning Our Narrative (by Angie Jones, on the history of the music industry so far, the changes in environment, tools, and business models musicians have had to go through so survive, and embracing changes and finding ways to fulfil our roles as software testers)
  • Learning Through Osmosis (by Maaret Pyhäjärvi, on mob programming and osmosis,  creating safe spaces to facilitate learning, and the power of changing some of our beliefs and behaviour)
  • There and Back Again: A Hobbit’s/Developer’s/Tester’s Journey (by Pete Walen, on how software was built in the old days, how testing and programming broke up into silos, and a challenge for both parties to go back at excelling at each other’s skills and teaming up
  • 10 Behaviours of Effective Agile Teams (by Rob Lambert, about shipping software and customer service, becoming a more effective employee, behaviours, and communicating well)

Cypress: Stubbing Network Requests with Cy.Route()

I very much enjoy testing web apps by simulating their network requests via code. This allows me to visit websites, login, and replicate functionality, all without a browser, a slightly different sort of testing than many testers are accustomed to. I love to explore what’s happening under the hood when we click elements and submit forms, I like to play with cookies and payloads, I try to find out what bare minimum of data do I need to pass through HTTP requests to recreate a particular user behavior. People often do this kind of testing with Postman but I’ve been accustomed to implementing tests with Ruby and the rest-client gem. Recently though I looked at how Cypress plays with network requests, especially curious about how they take it further with their built-in request stubbing feature using cy.route() because I have never tried stubbing before.

First, some context on HTTP requests:

  • GET requests often simulate visiting (or redirecting to) a web page or retrieving a resource (like an image or another file)
  • POST requests often simulate a form submission, like logins or payments, and as such deals with passing inputted data in order to proceed to the next application state
  • There are other types of HTTP requests but mastering how these two work is enough at the start

And here is an example of how Cypress helps you perform a said GET request:

and for a POST request:

Pretty straightforward and easy to follow. Notice that POST requests have more information in them than GET requests, since we’re passing data – the body field is concerned with user inputs while the headers field is concerned with the user session, among other things. Of course, both requests need a url field, some place to send the request to.

And when we send a request, we receive a response. That response tells us about how a web application behaved after the request – was the user redirected to another page? was the user able to log in? did an expected web element got displayed or hidden? were we sent to an error page, perhaps?

Cypress takes network requests further by introducing routing to testing. Here’s an example:

What the above code says is that we want to use Cypress as a server and we want to wait and listen for a POST request that’s going to the /login URL after a submit button (with an id of #submitButton) is clicked, after which we want to respond with a { success: false } result. This means that the actual response from our application from that url is going to be taken over by a fake response that we designed ourselves. This is what stubbing a network request looks like.

Now why would we want to do this? Some reasons:

  • We want to check how an application behaves for scenarios where a request fails to reach the application server. Do we redirect the user? Or do we show an error popup? Or does the application also work offline? To do this without stubbing, we would need some help from a programmer to shut down the app server at the right time after we perform the scenario.
  • We want to speed up tests by stubbing the response of some requests with less data than the actual responses deliver. We can even have the response data to be empty, if we don’t necessarily need that specific data for a test.
  • We want to see what happens to the application when it receives an incorrect response value from a request.

This is one thing I am loving about Cypress. Out of the box, they allow me to play with network requests alongside testing the user interface, and lets me tinker with it some more.