DEV Community: Andy Haskell

Conferencing tips as an autistic + ADHD conference-goer

Andy Haskell — Thu, 27 Feb 2025 06:23:21 +0000

I'm an AuDHD (autistic+ADHD) software engineer, and I've been going to tech conferences since OWASP Boston Application Security Conference 2010 when I was in college. I've gone as an attendee, a speaker, helping run a booth, and volunteering in conference programs like GopherCon Guides and GopherCon's Neurospicy Meetup.

In addition to the career benefits of conferencing, such as growing your professional network and seeing more perspectives on the tech you build with, they are also a great way to meet people you know from your favorite online communities. I love the tech conference greeting "Oh hey! I {App}-know you!". Some of my favorite memories in tech have happened at conferences, like hundreds of Gophers exploring New York City on a scavenger hunt at GothamGo, taking an impromptu trip to Red Rocks after meeting a new group of friends on Community Day at GopherCon Denver, and giving my very first tech conference talk at DevFest Albany with several new tech friends in the audience.

However, conferences can be challenging for neurodivergent conference-goers. It's easy to get overwhelmed with too much socializing, or with figuring out which events on the agenda to go to. And packing for a trip with ADHD - well, there's a reason there's so many memes about that in online neurodivergent communities. So I would like to share some of my tips for getting the most out of going to tech conferences while neurodivergnt.

⚠️ Before we start, just one thing to keep in mind, the advice I'm giving is not a definitive one-size-fits-all guide to conferencing while neurodivergent. There's no such guide since even people of the same neurotype can be very different from each other, including having different needs and priorities while conferencing. So instead, treat these tips more like building blocks you can use for building your guide to conferencing, and only use the ones that you find relevant.

Requesting and finding accommodations

Although I haven't formally requested accommodations for a tech conference, I do know that if there are accommodations you need, emailing the organizing team is a good way to request them. Often conferences have contact information for reaching out to organizers on their websites.

You can ask the organizers for details about the venue like its layout, ask about what accommodations are available for neurodivergent attendees, and specifically request accommodations that they might need more advance notice to get. In addition, some conferences put a field in their registration form for attendees to request accommodations you might need.

A few of the accommodations I've seen at conferences that an attendee might ask organizers about are:

Food at conference lunches that's compatible with dietary restrictions if you have any. Often the online registration form has an area for submitting information about dietary restrictions so that organizers can take that into account placing catering orders.
Live-captioning on the big screens for talks, which helps both people with hearing disabilities, and people who have challenges with auditory processing, which is a common issue for autistic people.
Some conferences have chillout areas set up for getting away from the action if you're overwhelmed. I've even heard of conferences that bring in therapy dogs in one area for conference-goers to play with.
- But even if a conference doesn't have a designated chillout area, the organizers could probably tell you where some good spots are in and near the venue to get a break from the action.
Reserved seats, such as closer to the stage for attendees with vision or hearing disabilities, or have another reason to need to be at the front.
The hidden disabilities sunflower lanyard is becoming an increasingly well-known symbol for someone to convey they have a non-visible disability, making it easier to ask for support as the symbol becomes more widely recognized. Besides at conferences, it's also being recognized at a lot of airports.

And remember there is no shame in needing accommodations, just like there is no shame in being neurodivergent or having a disability. So if you need accommodations, don't be ashamed about asking! And it's a good sign about the conference itself if the organizers make the process streamlined for getting accommodations or take the time to understand your needs.

A bag of tips on packing for the event

Packing for a trip while having ADHD can be challenging, since doing laundry and folding it is so stop-and-go, and it's easy to end up switching between categories of things to pack.

In order to make this more manageable, I wouldn't say I have a perfected technique, but some tips that have helped me with my packing, are:

Having dedicated pouches in my backpack for each category of things I'm packing. My bag has four major pouches and they are:
- Large electronics. I've found this dedicated pocket particularly makes it easier at airport security, so I only need to open one pouch in my bag to find all the electronics I need to put in their own bins.
- A dedicated pouch in the most secure part of the bag for all can't-lose items, such as my passport for international conferences. That way, once I show my passport at customs, I can put it there and know that that's the only place it could be until I need it again coming home.
- A pouch for TSA-approved travel-size personal hygiene.
- A pouch for notebooks, pens and pencils, and entertainment.
Leaving those dedicated backpack pouches open until everything for a given pouch is packed, so that the items inside remain visible, which helps with ADHD object-permanence.
Listing out absolute-must-have items. For example, prescription medications if you are taking any, your passport if you are travelling internationally for this conference, and items that your job required you to bring if you're going to the conference as part of work.
Laying out clothes by outfit, rather than by category. I've found that has helped me get a visualization of how many complete outfits (daytime outfits, pajamas, workout clothes, slightly-fancy attire for night events, clothes for any outdoor events) I have so far, and how much more laundry is left to do for my clothes to be completely packed.
Also when it comes to clothes, having a dedicated packing area in my apartment where I lay out those clothes, so that while remaining laundry is in progress, I don't mistakenly re-wear some of the clothes I wanted to pack
Bringing a dedicated reusable bag and saving for swag (the T-shirts, laptop stickers, and trinkets they give away at booths). At bigger conferences, there's a lot of swag you'll get, and that bag makes it easier to keep track of it all.
Speaking of swag, I recommend packing a couple fewer graphic T-shirts than you normally would for a trip, since it's common for companies to give out T-shirts as swag at their booths

Additionally, one other thing I plan on trying for next time I go to a conference is setting up a travel directory on my laptop with templates for packing checklists. That way, packing checklists can be reused and printed out with just small tweaks. I'm planning on making my own template, but searching "packing list template", I am finding a lot of pre-made templates online.

Prioritizing events to go to

Conferences can be overwhelming for neurodivergent attendees. They have a lot of socializing and being in crowds, with the main convention center events often going eight hours or more a day, plus all the afterparties. But one helpful thing I've found from going to so many conferences, is that you don't need to go to everything!

I find it useful to check the agenda once am considering getting my ticket to the conference, so I can pick out the events I really want to focus on being at. By doing that, it's possible to also pick times in the conference that I want to allocate as breaks to decompress. To pick out events, I keep track of three main categories of time blocks:

Time blocks where I committed to being at an event. This would be things like when I am on stage / at mic check if I'm a speaker, being at an event I signed up for as a volunteer, or being at the exhibitors' hall if I signed up for booth duty with work. It also includes workshops I had paid extra to attend, or meeting up with friends I made plans with.
- This also includes scheduling windows of time to eat and decompress.
Talks and or free workshops I really want to see. For me, that's primarily talks on areas of tech I want to learn more about, talks I could see directly benefitting my career, and talks where I'm friends with the speaker and want to hear them.
- I also like to allocate certain hours in this category to participate in the "hallway track" (tech slang for all the networking that happens in the convention center in between talks). That's a good way both to see friends I know from online tech communities like the Gophers and #CodeNewbie, as well as to grow my professional network by visiting the booths and social events like afterparties.
- This also can include seeing things in the area you really want to see. If I've got a conference in San Diego to go to, as an autistic guy with a lifelong Special Interest in animals, you'll definitely find me at the San Diego Zoo (namely at the red panda exhibit).
A remaining category, for if you have left-over social energy, you can also pick some "nice to see" events. For example I like learning in tech about topics that have nothing to do with my current job, so that I can learn about the tech I'd be interested in trying for a side project. So I make a point of going to talks on new areas of tech if I have the social energy, but if I don't, no sweat and no guilt.

If phone reminders help you, then you can put the events you're prioritizing into your phone's reminder app, and from those apps utilize 30-minute warnings. I find that to particularly come in handy for my most important events, and knowing when I need to get back to the convention center if I am seeing friends in town.

Staying regulated and doing self-care at the event

Conferences can be overwhelming for neurodivergent attendees with a lot of socializing and being in crowds, at an event that goes eight hours or more a day, plus going to afterparties. So make sure to do whatever you need to in order to prevent getting overstimulated, so have enough energy for the stuff you really want to see and do.

I particularly make a point of getting outdoors each day at the conference so that I can get some fresh air, as well as time to decompress by not having tech stuff on my mind. Sometimes that's going to things I wanted to see in the city, and other times it's just going exploring on a long lunch walk or eating on my hotel's rooftop when it's warm out.

And as I mentioned in the last section, you can actively allocate time in your go-to calendar app specifically for taking care of yourself and decompressing. And if you do need to exit a social event early because you ran out of social energy, that is completely an option. In my experience, people haven't cared if I've decided to dip from an event early.

If stimming helps you stay regulated, which it does for many autistic people, bring a stim toy. One I use is beaded lava rock bracelets; they're discreet since they're a fashion item, but rolling the beads makes them double as a good stim toy. They also make a cool way to represent your tech stack, by getting a stack of bracelets in the colors for the tech you use or tech communities you're involved in, such as blue for Go, green for Vue, yellow for Python, or purple for the #CodeNewbie community. And there are other discreet stim toys you can find as well online.

Decide for yourself how much you feel willing/safe to "be yourself" at a conference

In many neurodivergent communities, the term "masking" is used to refer to neurodivergent people avoiding expressing neurodivergent traits in order to blend in with their surroundings. This can be things like hiding stims (or making them more discreet as I mentioned before), trying to make more eye contact than normal if eye contact is expected, making small talk which many neurodivergent people find unnatural, or staying longer than you actually want to at an event. Masking may facilitate blending in, but it is stressful to mask for a long time, and it burns through social capacity.

Some reasons someone might mask at a conference are that they are on booth duty or in some customer-facing role at the event for work, or because they are networking on a job search and trying to maximize the odds that their first impression with the company they're talking to "lands" with them (and by the way, if you are a tech employer who wants to hire talented people of all neurotypes, working on making your hiring process neuroinclusive means you're not overlooking talented neurodivergent innovators). It is unfortunate, but there is still a lot of stigma around being neurodivergent, so there is some risk to showing neurodivergent traits.

However, many neurodivergent conference attendees choose to not mask, and sometimes even be vocally neurodivergent in conferences and other professional spaces. For example, they might choose not to suppress their stims because they want to regulate their energy levels to not get overstimulated. They might express their neurodivergent traits to make it easier for other neurodivergent people to find them, and help them "feel normal" expressing traits they might be masking.

Even when it comes to networking though, I have found that for my entire career, I've been able to use some of my neurodivergent traits to build my personal brand as well as make a lot of great friends in tech. Probably my own most well-known example is how I like to work references to sloths, an autistic Special Interest I've had since 2011, into tutorials that I write and on my posts in tech social media communities. And I'll let you in on a secret about non-tech Special Interests at tech conferences, after a few hours into the convention, it's refreshing to hear people at the hallway track talk about something that isn't tech, or bring up an angle to the tech that they haven't considered. So networking doesn't necessarily have to mean completely masking.

Whether and how much for you to mask though, is a decision that is yours to make. As an example, for myself one big reason I like to be overtly autistic and ADHD at conferences when I feel safe to, is to de-stigmatize neurodivergence by making it so more people hear about it from our actual perspectives, rather than from the many harmful stereotypes spread about us. However, in more formal settings, I still have some degree of masking to blend in and follow professional etiquette, and to make what I am saying clearer for neurotypicals to understand. So only mask as much or as little as you are willing and feel safe to.

Another tip, at tech conferences, check the program because you might be able to find events where you can be yourself more. For example, outings related to doing something you really like. And you may even find that there is a neurodiversity-focused event at your conference! For example, since 2023, GopherCon has had a Neurospicy meetup for neurodivergent people, people questioning their neurotypes, and neurotypical allies. They rent out a bar, the music is turned down to prevent auditory overstimulation, and people hang out and talk over catered free food, trading Special Interests. I've been there twice, and it was a highlight both times!

Regardless of your neurotype, I hope at some of my tips help you with having a memorable time at tech conferences, and with growing your tech career from conferencing, and if you learned something new about neurodiversity, I would love to hear about it! 🌈♾️

How AuDHD traits have helped me get good at devrel

Andy Haskell — Sun, 14 Apr 2024 18:50:44 +0000

Developer relations (devrel) might not be front of everyone's mind as a career that a neurodivergent person would excel in. However, not only are there many neurodivergent people already succeeding and trailblazing in this field, many neurodivergent traits can actually be conducive to great devrel.

To demonstrate what I mean, I'd like to talk about some of my own neurodivergent traits that have helped me get good at devrel in the Go, JavaScript, and #CodeNewbie communities. I am AuDHD (autistic + ADHD) and although I haven't formally worked in a devrel role, I'd still call myself devrel-adjacent. I have done a lot of devrel work through tutorial-writing, event organizing, open-source contributions, and participating in social media tech communities, and my neurodivergent traits have been integral to my devrel style.

⚠️ Two things before we begin:

While I am talking about my own AuDHD traits, please note that I am just one AuDHD person, and that even people who are neurodivergent in the same way don't all have identical traits and skills. So please do not treat me as representative of all AuDHD people. A common adage in the autistic community is "if you meet one autistic person, you've met one autistic person".
As I will talk about in more detail at the end of this blog post, please do not take away from this "neurodivergence is a super power". While neurodivergent traits can help someone in some aspects of life, they can be disabling in others. Therefore, accommodations still matter for neurodivergent tech workers.

Special Interests

One of the most well-known common autistic traits is Special Interests. It's where an autistic person gets intensely focused on some topic. The one that's become an autistic stereotype is a Special Interest in trains (some of us do have that Special Interest, some don't), but really any topic can be a Special Interest. For example I've been a bio guy basically since I found out nature documentaries were a thing!

Special Interests have helped me do devrel work in three ways. First, they get me motivated to understand a tech stack in-depth. Second, it makes me want to teach others everything I've learned (this is another common autistic trait, infodumping). And third, the most devrel-relevant part, it makes me excited to participate in communities around the tech that I work with.

Probably the most salient example of this in my devrel, was getting a Special Interest in Go in 2014. Soon after getting the hang of Go's net/http package, I started tweeting about it and writing Go tutorials. This led to me making friends with a lot of other Gophers (people who code in Go), and when the Boston Go meetup launched, I quickly became an enthusiastic regular at the meetup, and I've participated in the Go community through tutorial-writing, public speaking, and working on the organizing team for Boston Go.

Besides Special Interests directly in tech though, Special Interests can also be used to add a personal touch to your devrel. I got a Special Interest in sloths through a friend in college, and since then sloth facts have been a signature part of the examples I use in my blog posts and talks. 🦥

ADHD novelty-seeking

A common ADHD trait is novelty-seeking - seeking out new things and new experiences. It's why growing up I went through so many video games. It's also why in my tech career, even though for my actual jobs I've primarily done backend web engineering in Go, outside of work, I've accumulated a lot of other tech skills like the JavaScript frontend ecosystem, terminal UIs, accessibility, and Ruby.

This ADHD novelty-seeking, and autistic Special Interests, make a potent combination in devrel, because novelty-seeking in a tech stack someone knows in-depth leads to helping developers see how that tech can solve real-world problems, which can lead to really practical tutorials (with some Special Interest-driven fun mixed in!). And meeting developers where they are, whether they're hobby developers or they use your tech at work, is a key part of an impactful devrel program, since that gets more people using your tech and participating in its community!

Likewise, since using a lot of different tech means spending a lot of my time being a newcomer in it, that leads to finding aspects of "getting stuff done" with a tool that aren't talked about enough in a newcomer-friendly way. My first blog post to get more than 10,000 views was this tutorial on webpack, which came out of spending A LOT of time getting tangled up in the frontend JavaScript ecosystem. The webpack resources I found were well-written for experienced frontend developers, but I found them challenging to follow as a newcomer and I felt like I was missing some core concepts. So after cobbling together a webpack build that gave me what I needed, I worked backwards to write a from-the-ground-up webpack tutorial (also, 14-minute read, talk about infodumping! 😅).

Attention to detail

One more AuDHD trait I would like to talk about is autistic precision. Many autistic people prefer to do things precisely and give precise answers to questions. This often can make an autistic person come off as pedantic, but when you're writing documentation, a from-the-ground-up tutorial, or in general giving instructions, this can be advantageous.

In coding in general, not just devrel, this attention to detail can lead to sniffing out bugs that are easy to overlook, or detecting the potential for a bug or technical debt before the coding on an assignment has even started. And for me, because my devrel comes out of a "learning by doing" approach, when I learn a new framework, I find myself spending a lot of time pondering "would this approach still work in [this scenario I'm eventually gonna run into on this project]?" And that sort of attention to detail in devrel leads to laser-carved documentation that lets developers know about edge cases, give realistic examples of how the code is used, and clarify differences between similar pieces of functionality.

This attention to detail also can mean that for key abstractions in a tool or framework, what concretely goes on doesn't go unexplained. For example, when I was learning Go for web development, my first stumbling block was understanding how interfaces worked, particularly http.Handler, which is key to doing web development with Go's powerful net/http package and the fits-like-a-glove package built on top of it, the Gorilla Mux router. My way of finding out how that worked, and seeing the elegance of that interface, was pretty unorthodox - I figured out how Handlers worked by looking directly at Go's source code (which also is a demonstration of Go's readability, if you're interested in joining the Gophers!). And coming out of that was my very first tech talk at in 2015, on learning Gorilla from its Node.js counterpart, Express.js!

Accommodations still matter

While in this post I talked about how my AuDHD traits have shaped my devrel work, one thing you shouldn't take away from this talk, especially if you run a devrel program, is the common cliche "neurodivergence is a super power". While neurodivergent traits often can be strengths in some areas as I've shown, they can be disabling in other areas. This is why it is still important in devrel, like in all workplaces, disability accommodations are still important.

For example, one flip side to my eye for detail, is perfectionism in my work. So as a software engineer, whenever I'm working on a team and there are time constraints to work around, I find it really helpful coordinating with a teammate to determine which things to prioritize and make a plan for when to address a concern I noticed from a low-level detail. Also, with ADHD, I find it really helpful to allocate dedicated distraction-free focus time. And while I don't use this accommodation myself, one accommodation I have heard of people using is AI transcriptions of major meetings so that people can go through the discussion of a meeting at their own pace.

Many accommodations, by the way, can have benefits for your whole team. For example, if it's the norm on a team for people to respect each other's focus time, that can lead to the whole team, including neurotypical (non-neurodivergent) employees, being able to do distraction-free work. Meeting recordings and transcripts have a side benefit also mean someone can watch a meeting even if it happened outside of work hours in their time zone.

Neurodiversity strengthens devrel!

While I didn't want you taking away from this that neurodivergence is a super power, the takeaway I do want to give is that like other forms of diversity such as racial, gender, LGBTQ, cultural, and age diversity, I firmly believe neurodiversity strengthens devrel! Yes neuroinclusion and all forms of inclusion in the workplace take effort, but I believe putting in that groundwork sets a team up for success.

On a neurodiverse team where neurodivergent and neurotypical people are supported and respected, you get perspectives of people teaching about your tech from different styles of thinking. This is incredibly impactful when you're teaching about a platform, tool, or framework, because people using your tech and participating in its community also have a wide range of problem-solving styles and questions they need answers to when they're using your tech. Additionally, on a neuroinclusive team, your neurodivergent team members don't get burnout so easily, which means they're more likely to stick around and become great mentors and leaders in your team! This is all on top of the ways I've mentioned that neurodivergent traits can be strengths for individuals doing devrel work.

To end this post, since as I said in the beginning, I am only one AuDHD person, if you're neurodivergent and do devrel in any capacity (whether developer advocate is your formal job title, or you give tech talks from time to time), and you feel comfortable sharing, I'd love to hear your perspective on if/how you feel your neurodivergence shapes how you do devrel!

And happy Autism Acceptance Month! 🌈♾️

Write your tech talk slides rapidly with Marp

Andy Haskell — Tue, 14 Nov 2023 05:57:21 +0000

I've been doing public speaking in tech since 2015 when I presented my very first lightning talk at Boston Go, and since then, I've given talks at meetups, at work, and at a couple conferences.

But while I love speaking at events to teach tech concepts I've learned, there can be some friction getting the ideas from my brain to my slides, with thinking through slide layouts and polishing the slides so my talk flows well from slide to slide.

What's helped me with writing slides lately though, is a tool called Marp, which allows me to write my slide layout by typing just in my text editor in Markdown. Which for me means:

🏎️ Because Marp has sensible built-in layouts, I don't need to think about things like font size until I have a reason to; I can just type like I would for a blog post, and the slide will look good enough that I can practice with it right away, and tweak its layout later!
👀 Since I'm writing slides in my editor, if I want to switch to experimenting with the code that my talk is covering, that's much less of a context-switch for me than going between a drag-and-drop slide tool and a text editor.
- Speaking of preventing context switching, there's also a Marp plugin for VSCode that you can use to see your slides side by side with the text you're writing, in real time!
🦕 Since my slides are made of text, that makes it easy to have different versions of my talk versioned in Git, so as I experiment with different arrangements of slides, I can switch versions as fast as you can say git checkout!
🎨 You can tweak your layout either for individual slides, or all slides, using CSS!

And I can say that Marp is conference-ready, since it's what I used for writing and iterating on my slide deck at GopherCon this year!

So I'd like to show you in this tutorial how to use Marp to write three types of slides: A title slide with an eye-catching image, an "about me" slide with an image on the left and text on the right, and a code snippet slide. I'll also show you how to add speaker notes that only the speaker can see while presenting, and how to use CSS to give your slide layout more customization.

Installing Marp

For getting Marp, you install its command-line interface with a package manager, like Homebrew, Scoop, or Yarn.



yarn global add marp-cli

With Marp installed, let's write our slide deck!

Writing our first title slide

First, let's give our talk a title slide. Paste this Markdown into a file named talk.md.



---
marp: true
theme: uncover
paginate: true
---

# What is io.Reader in Go?

YOUR NAME - @YOUR_SOCIAL_MEDIA

We've got two pieces of Marp syntax written now: At the top, the section full of options inside the triple dashes is called the frontmatter, and it contains configuration for your presentation as a whole.

The rules in our frontmatter are:

marp: true, which indicates that this is a Marp presentation
theme: uncover, which sets your slides' theme to Uncover, one of the built-in themes from Marp.
paginate: true, which causes your slides to include a page number.

There's other rules you can add in your frontmatter as well, such as style for additional custom CSS styling, or backgroundImage if you want your slides to all have a default background image, such as a patterned background to make your slides look more flashy.

Below the frontmatter, we have our first slide written in Markdown.



# What is io.Reader in Go?

**YOUR NAME - @YOUR_SOCIAL_MEDIA**

Just like in standard markdown, the text represents a header for the title of your talk, and regular text in bold for your name and social media account.

To see what this slide actually looks like in a presentation, run the Marp CLI we just installed:



marp -w talk.md

You will then get a prompt to go to a localhost URI. Navigate to there in your browser and you'll
see your slide deck. So far, the title slide looks like this:

We've got our header and name. This is a nice clean layout for a title slide, but what if we wanted a cool image to kick off the talk with? You can add that with some Markdown for an image.

Adding an image

Similar to in standard Markdown, in Marp you use the ![alt text](image URL) format for rendering images. To try this out, we'll use a photo I got of the bright blue waters on a beautiful day at the beach.



![Picture of the view at the beach; rocks are in the foreground and the water that day was bright blue](https://url/to/beach/image)

# What is io.Reader in Go?

YOUR NAME - @YOUR_SOCIAL_MEDIA

---

Now look at talk.html, and

Woah that's a tall image! If we want this image to fit on the slide, we're going to need to resize it, and we would do so by adding a directive to the alt text, and also making the header's text smaller by converting it from an h1 header to an h3 header.



![w:800 h:480 Picture of the view at the beach; rocks are in the foreground and the water that day was aqua](https://url/to/beach/image)

### What is io.Reader in Go?

With the directives w:800 h:480, we're having Marp set the width and height of the image to 800 pixels and 480 pixels, respectively, fitting neatly in the slide.

Or if you really want to be flashy and make an image that takes up the whole background, you can use the bg directive!

![bg Picture of the view at the beach; rocks are in the foreground and the water that day was aqua](https://url/to/beach/image)

But you'll want to ensure the text contrasts with the colors on the image that it might overlap with. We'll look at one way to do that using drop-shadow text in the section on CSS.

Adding an "about me" slide

To write a new slide, you separate each slide in Marp by adding a line containing three dashes, like this:



![w:700 h:500 Picture of the view at the beach; rocks are in the foreground and the water that day was bright blue](https://url/to/beach/image)

# What is io.Reader in Go?

YOUR NAME - @YOUR_SOCIAL_MEDIA

---

Everything from here down to
the next --- line will be
will be part of the Markdown of
the second slide of your talk,
and then you add another --- to
give your talk a third slide

We'll replace the placeholder block of text with an "about me" slide that follows a common layout for slides: An image taking up the left side of the slide, and text on the right.

And we'll be doing this using a parameter of the image bg directive we saw earlier, which makes the bg image only be the left side of the slide: bg left. For this example, let's have my dog Lola give this talk.



---

![bg left 70% My dog Lola, an adorable black and white Havanese dog who looks like a tiny floofy panda, on the couch looking at the camera doing a blep](https://url/to/lola/image)

# About me

- **Name:** Lola the Micropanda
- **Job:** CFO at Micropanda Accelerator
- **IG:** @lolamicropanda

Open up your Marp slide deck and you'll see:

Lola's "about me" slide! Notice in addition to the left parameter on the bg directive, I also decided to add a 70% parameter. This makes it so the image takes up the middle 70% of the left of the slide, rather than the whole left side of the slide, making the "about me" image appear as a stripe across the left of the slide.

By the way, you know the technique of presenting a bulleted list where you display the bullet points one by one as you present? Like "A bit about me [show bullet point], I'm Lola the Micropanda, [show another bullet point], I'm Chief Floof Officer of Micropanda Accelerator [show one more bullet point], and you can follow me on Instagram at @lolamicropanda"?

Marp supports that as well! If you change the bullet points from dashes to asterisks, like this



* **Name:** Lola the Micropanda
* **Job:** CFO at Micropanda Accelerator
* **IG:** @lolamicropanda

You get a fragmented list; go through the "about me" slide in talk.html and now when you present, your bullet points appear one by one!

Code snippets and speaker notes

Just like how Marp supports images, headers, regular text, and lists, you're also able to have slides in Marp that contain code snippets. Just like in standard Markdown, you make a code snippet with the triple backticks (replaced with a message in brackets for the code snippets ahead because I was having trouble rendering triple backticks inside a code snippet).



## io.Reader in Go: small interface with tons of power

[replace this box with triple backticks in your code]
type Reader interface {
    Read(p []byte) (n int, err error)
}
[replace this box with triple backticks in your code]

---

If you look at this slide in your talk.html, you'll see:

Your code on a slide, formatted to monospace! Though you might want syntax highlighting on your slides, and if you do, then there's a simple tweak you can do: before the leading backticks, type the programming language your code is in. My code is in Go, so I am leading with go at the end of the triple backticks.



- [replace this box with triple backticks in your code]
+ [replace this box with triple backticks in your code]go
  type Reader interface {
      Read(p []byte) (n int, err error)
  }

Now your slide will have syntax highlighting.

And if I was giving this talk for real, this would be a slide where speaker notes would really come in handy, since there's several things I'd want to point out about Go's io.Reader interface.

Not every speaker uses notes, but if you use speaker notes or want to try them, Marp lets you give any of your slides some notes that only you'll see when you present using HTML-style  comments. I personally find them useful for the flow of my talk since it gives me reminders of concepts I want to bring up, or as timing cues such as to go to the next slide mid-sentence. Here's an example



<!--
The io.Reader interface is a type you'll see all over the Go interface, with just one method. Let's look at that method's signature.

* In the return value n is the number of bytes read to the buffer
* err can include EOF for reaching the end of the input
* The part I found surprising was we don't return the bytes we read, we copy them to a buffer we pass in. And the reason why is-[CHANGE SLIDE]
-->

---

To use your speaker notes, open talk.html, mouse over the slides, and click the lectern icon at the right of the menu that opens. Now you're in presenter view just like in drag-and-drop tools. So you'll have one desktop window showing the current slide, which you share to the audience, and the other showing your speaker notes, the current slide, and a thumbnail of which slide is next.

Using CSS in your slides

The layout for Marp slides does have sensible defaults, but you are able to customize your slide's layout with the full power of CSS, by inserting a <style scoped> HTML tag into a single slide, or a <style> HTML tag to add CSS rules that apply to all slides.

First up, on our slide showing the code to Go's io.Reader interface, while I like having a small amount of information on each slide in order to reduce cogntive load, with so little code on the slide, the code could use a bigger font size to take up more of the screen. Here's how we'd do that:



---

<style scoped>
code {
  font-size: 40px;
}
</style>

## io.Reader in Go: small interface with tons of power

[replace this line with triple backticks in your code]go
type Reader interface {
    Read(p []byte) (n int, err error)
}
[replace this line with triple backticks in your code]

---

Look at this slide in talk.html, and you'll see the code now takes up more of the screen.

Next up, remember how I mentioned we can have our title slide be a background image with text on it using an image's bg direcctive, but we'd want to use CSS to ensure our text is legible?

Here's the CSS we'd add that for a title slide. Notice we're also changing the header back to an h1 since the image is now a background image so we don't need to conserve space with an h3 header.



<style scoped>
h1, p {
  color: #FFFFFF;
  font-weight: bold;
  text-shadow:
    5px 5px 3px #000000;
}
</style>

![bg Picture of the rocks on Singing Beach; rocks are in the foreground and the water that day was bright blue](https://url/to/beach/image)

# What is the io.Reader interface in Go?

YOUR NAME - @YOUR-SOCIAL-MEDIA

---

The rules make all the text on that slide (a "heading 1" and a paragraph, or h1 and p in CSS and HTML) white, bold-faced, and with black text-shadow down and to the right. Here's how that looks in talk.html

Awesome! As one last thing to look at, let's say we want to ensure the content of your slides doesn't cross into the bottom 20% of the slide. This is a scenario you might see if a conference has live captioning and wants to place the live captions in the bottom 20% of the screen, which GopherCon did.

When I found that out, I was able to quickly throw in <style scoped> tags to get all my slides taking up 80% of the screen, but what could have gotten that done faster, was if I had instead used a <style> tag without the scoped to apply 20% padding to the bottom of all slides!



<style>
section {
  padding-bottom: 20%;
}
</style>

This works because in the HTML that the Marp tool produces, an individual slide is a <section> HTML element.

This does though raise up the content of all existing slides by 20%, so if you apply this to your slide layout after you've already gotten some slides written, you'll still want to look at your existing slides and make sure you don't need to further tweak any individual slides' layouts.

One other thing, if your page has too much content on it or too big an image, it's still possible for a slide to go past a height cutoff, so one trick I learned at the GopherCon rehearsal (can't remember who told me that but whoever that was thank you!) was to temporarily change the background image of my slides to a 5 x 5 grid, with a red horizontal line at 80% height.

You can apply that background image to all slides (except slides with their own background image, like our newly upgraded title slide) using backgroundImage in the frontmatter.



---
marp: true
theme: uncover
paginate: true
backgroundImage: url('https://url/to/cutoff/image.png')
---

With that background image, this is what the code slide looks like, well above the 80% mark!

If you were interested in Marp, hopefully this helps get you started writing slides in Marp! I'd also be interested to hear about what other tools you've used for making the process of writing a tech talk more ergonomic, so if you've used any other tools, I'd love to hear about them in the comments!

Using Testify Mock in web clients

Andy Haskell — Mon, 24 Oct 2022 14:08:12 +0000

In the last tutorial, we looked at:

How Testify Mock helps us make nondeterministic code testable
How to implement an interface using an embedded Testify Mock
What the general flow of a Testify Mock test looks like

We demonstrated that on random numbers first, since that's the simplest nondeterministic code to be working with.

However, the use case of Testify Mock that ultimately got me learning about that package, was to use it in code that builds on top of clients to web APIs.

The reason code using web API clients is nondeterministic to test is, you don't have total control over what you get back from a web server for a given input, for reasons such as:

✍️ The data you get back for a given server endpoint might change, either slightly or dramatically.
🚧 The server might be down altogether.
🐆 You might be being rate-limited from sending too many requests to the server.
🐛 You'll want test coverage so that your code does the right thing if the server you're talking to is giving back 500s. But since a 500 by definition is an internal server error, it's not necessarily possible to reliably get 500s, especially in the long term.

So for tests where you want the same output every time you run the same API client call in your test, that's a great use case for Testify Mock. So for this tutorial, we'll see how Testify Mock can be used as one of your tools to write test coverage when your Go code's got some Internet to do!

📚 Setting up a fake API to test against

The code we're going to test uses a client for an API that the zoo set up to give facts about animals.

The endpoint our code will be talking to is GET /animal-facts?species={species}&page-token={page-token}, and it returns a JSON object containing a page worth of animal facts, plus a token if there's another page.

If you're following along, copy the code ahead into a file named something like client.go. The main takeaway is that we have a ZooHTTPClient for talking to the zoo's API, and we call the /animal-facts endpoint with the method ListAnimalFacts()

package main

import (
    "fmt"
    "net/http"
)

type ZooHTTPClient struct {
    baseURL string
    client *http.Client
}

// Serialization of error response from zoo API service
type ErrorResponse struct {
    StatusCode int    `json:"status_code"`
    Message    string `json:"message"`
}

func (res *ErrorResponse) Error() string {
    return fmt.Sprintf("got %d error: %s", res.StatusCode, res.Message)
}

type AnimalFactsQuery struct {
    AnimalName string
    PageToken  string
}

func (c *ZooHTTPClient) ListAnimalFacts(q AnimalFactsQuery) (*AnimalFactsResponse, error) {
    // HTTP implementation here; returns an
    // AnimalFactsResponse if the HTTP request succeeds,
    // or an error, of type ErrorResponse, if the request
    // gets a non-2xx HTTP status code.

    // returning nil, nil just so the code compiles
    return nil, nil
}

type AnimalFactsResponse struct {
    Facts         []string `json:"facts"`
    AreThereMore  bool     `json:"are_there_more"`
    NextPageToken string   `json:"next_page_token"`
}

And here is the code we want to test, which we'll copy to a file like main.go. In that code we pass the API client into getSlothsFavoriteSnack so we know what snack to donate a whole bunch of to the zoo. The function returns that snack as a string on success, or if that's not mentioned in any of the facts from the API, then we return errFactNotFound and dust off that library card in order to find that information.

⚠️ NOTE: There is a bug in this code. Don't spend a bunch of time looking for it now, though, we'll fix it when we find that bug using our tests!

package main

import (
    "errors"
    "regexp"
)

var errFactNotFound = errors.New("fact not found")

var favSnackMatcher = regexp.MustCompile(
    "favorite snack is (.*)",
)

func getSlothsFavoriteSnack(c *ZooHTTPClient) (string, error) {
    // Until we're at the last page of facts, call ListAnimalFacts
    // with the current page token to paginate through the list,
    // exiting when either the response's AreThereMore field is
    // false, or we find out what sloths' favorite snack is.
    var pageToken string
    for {
        res, err := c.ListAnimalFacts(AnimalFactsQuery{
            AnimalName: "sloth",
            PageToken:  pageToken,
        })
        if err != nil {
            return "", err
        }

        // check if any facts match the "favorite snack is"
        // regex and if so, return the match
        for _, f := range res.Facts {
            match := favSnackMatcher.FindStringSubmatch(f)
            if len(match) < 2 {
                continue
            }
            return match[1], nil
        }

        // check the response to see if there are any more
        // pages of facts about sloths
        pageToken = res.NextPageToken
    }

    // otherwise if the fact about sloths' favorite snack
    // isn't in the zoo API, return errFactNotFound.
    return "", errFactNotFound
}

Since ListAnimalFacts talks to the server for the zoo's API, the code is nondeterministic. So testing it in a repeatable way is a great use case for Testify Mock.

🥸 Basic test with mock

If you recall from the last tutorial, the steps to doing a test with Testify Mock are:

Take the nondeterministic piece of functionality and wrap it in a Go interface type.
Write an implementation of the interface that uses Testify Mock.
In the tests, use the mock implementation to select deterministic results of the functions your interface calls.

So to start, let's make an interface for our API client.

Wrapping our client in an interface

type ZooClient interface {
    ListAnimalFacts(q AnimalFactsQuery) (*AnimalFactsResponse, error)
}

If we had additional client methods used in our code, such as for other endpoints on the API, we would also add those methods to the ZooClient type as well, but for this tutorial we're only testing code that uses ListAnimalFacts.

Now, to enable using a mock in getSlothsFavoriteSnack, we change that function's signature to take in a ZooClient rather than a *ZooHTTPClient.

- func getSlothsFavoriteSnack(c *ZooHTTPClient) (string, error) {
+ func getSlothsFavoriteSnack(c ZooClient) (string, error) {

Writing a mock implementation of our client

And now just like with the random number generator in the last tutorial, we can use the mock.Mock type to write a mock implementation of our client.

package main

import (
    "github.com/stretchr/testify/mock"
)

type mockClient struct { mock.Mock }

func newMockClient() *mockClient { return &mockClient{} }

func (c *mockClient) ListAnimalFacts(
    q AnimalFactsQuery,
) (*AnimalFactsResponse, error) {
    args := c.Called(q)
    if args.Get(0) == nil {
        return nil, args.Error(1)
    }
    return args.Get(0).(*AnimalFactsResponse), args.Error(1)
}

Just like in the last tutorial, we start by making a mock client that embeds a mock.Mock object, and we retrieve the return values we assigned to the passed-in parameters using Mock.Called.

Unlike in the random number generator example, though, the object we're returning is an *AnimalFactsResponse rather than a primitive Go type like an int. So to get our response as the type we want, we call args.Get(0) which returns an interface{}/any that we then can convert to the type we want with .(*AnimalFactsResponse).

Using our client in a test

Now, let's use our client in a test!

import (
    "testing"
)

var firstPageAPIReq = AnimalFactsQuery{
    AnimalName: "sloth",
    PageToken:  "",
}

func TestGetSlothsFavoriteSnack(t *testing.T) {
    c := newMockClient()
    c.On(
        "ListAnimalFacts", firstPageAPIReq,
    ).Return(&AnimalFactsResponse{
        Facts: []string{
            "Sloths' slowness is actually used as a form of camouflage",
            "Baby sloths make the cutest li'l squeak 🥰",
            "Sloths' favorite snack is hibiscus flowers",
        },
        AreThereMore: false,
        NextPageToken: "",
    }, nil)

    favSnack, err := getSlothsFavoriteSnack(c)
    if err != nil {
        t.Fatalf("got error getting sloths' favorite snack: %v", err)
    }

    if favSnack != "hibiscus flowers" {
        t.Errorf(
            "expected favorite snack to be hibiscus flowers, got %s",
            favSnack,
        )
    }
}

First, we pass in the AnimalFactsQuery we're going to use to c.On() and assign it a mock API response with c.Return().

Now our mock client is ready to use; we call getSlothsFavoriteSnack, and it uses our mock client; when it calls ZooClient.ListAnimalFacts, it gets back our API response, loops through the Facts in the API response, and when it reaches the one titled Sloths' favorite snack is hibiscus flowers, that matches the regular expression, so getSlothsFavoriteSnack returns "hibiscus flowers", nil.

Finally, back in our test, we verify that favSnack is hibiscus flowers and err is nil, just like we would if this test was using a client pointed at and authenticated to a real zoo API.

Run the test, and you'll see that it passed and that sloths love hibiscus flowers! 🌺

Just like that, we've got a Go test on what happens when our code gets back a certain response from an API, and we can run it any time we want with the same result from our mock API; if the zoo's real API server is down, then this test will still run successfully since we're not talking to the real API!

Speaking of when the server is down, we don't want to test just the happy path; we should have some test coverage for what happens if we get an error calling getSlothsFavoriteSnack too.

⛔️ Handling error cases

There's a couple error cases from the API we should have test coverage for:

The server is giving back 500's, which as I mentioned at the beginning of this post, is hard to re-create with a real API.
The API doesn't have the animal fact we want.

Testing that our code handles internal server errors correctly

Let's start with testing the 500 internal server error case.

func TestGetSlothsFavoriteSnack500Error(t *testing.T) {
    c := newMockClient()
    c.On("ListAnimalFacts", firstPageAPIReq).Return(
        (*AnimalFactsResponse)(nil), &ErrorResponse{
            StatusCode: 500,
            Message: "server error",
        },
    )

    _, err := getSlothsFavoriteSnack(c)
    if err == nil {
        t.Fatal("got nil error from getSlothsFavoriteSnack")
    }

    errRes, ok := err.(*ErrorResponse)
    if !ok {
        t.Fatalf("expected error to be ErrorResponse, got %T", err)
    }
    if status := errRes.StatusCode; status != 500 {
        t.Errorf("expected 500, got %d status code", status)
    }
}

Like before, we set up a mock response for firstPageAPIReq in c.On().Return(). But this time, rather than passing in a successful response, we pass in a nil AnimalFactsResponse and an ErrorResponse as our error.

Then, we call getSlothsFavoriteSnack and validate that we got an error, it's of type ErrorResponse, and that its status code is 500. So when we run the test, once again it passes.

Testing the error case where the API doesn't have the sloth fact we want

Now that we've got a test for our 500 error, let's test the case where we don't have the sloth fact we want. In that case we expect that getSlothsFavoriteSnack returns errFactNotFound.

func TestGetSlothsFavoriteSnackNotFound(t *testing.T) {
    c := newMockClient()
    c.On(
        "ListAnimalFacts", firstPageAPIReq,
    ).Return(&AnimalFactsResponse{
        Facts: []string{
            "Sloths' slowness is actually used as a form of camouflage",
            "Baby sloths make the cutest li'l squeak 🥰",
            "Sloths need their beauty sleep, plz send noise-cancelling headphones",
        },
        AreThereMore: false,
        NextPageToken: "",
    }, nil)

    if _, err := getSlothsFavoriteSnack(c); err != errFactNotFound {
        t.Fatalf("should have gotten errFactNotFound, got %v", err)
    }
}

We start with a similar test setup to the success case, except this time around, the response we set up doesn't include information about what sloths like to eat. So at the bottom of the test, we assert that the error we get back is errFactNotFound and that we should head to the library.

Run this test though, and you should get an infinite loop; if you wait about 10 minutes the test will fail because getSlothsFavoriteSnack never returns, so the test times out.

In other words, we found a bug in getSlothsFavoriteSnack. If you recall, this was the for loop in there:

for {
    res, err := c.ListAnimalFacts(AnimalFactQuery{
        AnimalName: "sloth",
        PageToken:  pageToken,
    })
    if err != nil {
        return "", err
    }

    for _, f := range res.Facts {
        match := favSnackMatcher.FindStringSubmatch(f)
        if len(match) < 2 {
            continue
        }
        return match[1], nil
    }

    pageToken = res.NextPageToken
}

We use a for loop because this API is paginated so that if there's more than one page worth of sloth facts, we can check the next page. The bug is that we never break out of the for loop if we're at the end of the list of sloth facts, as specified by the AreThereMore field on the response. If you've tricked out your editor, that might have told you that the line returning errFactNotFound was unreachable, and that's why.

So let's fix the bug!

    for _, f := range res.Facts {
        match := favSnackMatcher.FindStringSubmatch(f)
        if len(match) < 2 {
            continue
        }
        return match[1], nil
    }

    pageToken = res.NextPageToken
+   if !res.AreThereMore {
+       break 
+   }

Run the test again and now our test should pass!

📖 Pagination with MatchedBy, Once, and AssertNumberOfCalls

As one last thing to test, since the API is paginated, we also should have some test coverage for when the information about sloths' favorite snack isn't on page 1.

In this API we're mocking, requests and responses include a PageToken/NextPageToken field, to tell the API which page of sloth facts to retrieve. So a test for the scenario where the search results are on the second page might look like this pseudocode:

Add a mock for page 1, where the AnimalName is "sloth" and PageToken is a blank string.
1. Have that mock API call return our search results, AreThereMore=true, and NextPageToken=NEXT.
Add a mock for page 2, where AnimalName is "sloth" and PageToken is "NEXT".
1. Have that mock API call return a second page of search results; AreThereMore=false and page 2 contains the information that sloths love hibiscus flowers.
Run getSlothsFavoriteSnack and check that "hibiscus flowers" is still retrieved.

We could pass each individual query into Mock.On(), and that wouldn't be too difficult to write in this example code. However, if this API was more complicated and we were testing more-complicated fields, it can be a pain to ensure that each call to Mock.On has exactly the right fields on the structs we're passing in. In particular, you might have a more complicated function than getSlothsFavoriteSnack you want to test, where it takes a lot of staring at your code in order to figure out the exact arguments each individual API call has.

In this test we're running, we're not that worried about the exact content of the PageToken field, since API page tokens tend to be pretty opaque. Whether the page token says something like "page 2", "some more facts on the next page", or a UUID. Essentially, we're not the ones who care about the page token's formst; the zoo's API team is in charge of that!

What we're really testing in a TestGetSlothsFavoriteSnackResultIsOnTheSecondPage (that's a mouthful!) test is that if the information we want is on the second page, we're still able to retrieve it with another query for sloth facts. And there's a handful of functions that can help us test that, to a reasonable "just the important stuff" level of detail, which are:

MatchedBy; instead of passing in an argument to Mock.On() that the argument in the test has to exactly match, you pass in a function that defines the criteria for whether an argument in the test matches the argument to Mock.On().
Once; specify arguments and return values with Mock.On().Return() that are only to be called and given back once. For example in a paginated API, the arguments you call in each round of the loop are nearly the same, so you can add Once() on to your mock call to say "give us back each page of results only once".
AssertNumberOfCalls; if the mocked-out code you're testing is called in a loop, this allows us to check that the loop ran the expected number of times.

To try these out, let's give some test coverage where sloths' favorite snack is on page 2.

func reqSlothFacts(q AnimalFactsQuery) bool {
    switch strings.ToLower(q.AnimalName) {
    case "sloth",
        "lemur: caffeine-free edition",
        "descendants of the giants who made today's avocados happen":

        return true
    default:
        return false
    }
}

var page1 = AnimalFactsResponse{
    Facts: []string{
        "Sloths' slowness is actually used as a form of camouflage",
        "Baby sloths make the cutest li'l squeak 🥰",
        "Sloths need their beauty sleep, plz send noise-cancelling headphones",
    },
    AreThereMore: true,
    NextPageToken: "some more facts on the next page",
}

var page2 = AnimalFactsResponse{
    Facts: []string{"Sloths' favorite snack is hibiscus flowers"},
}

func TestGetSlothsFavoriteSnackOnPage2(t *testing.T) {
    c := newMockClient()
    c.On("ListAnimalFacts", mock.MatchedBy(reqSlothFacts)).
        Return(&page1, nil).
        Once()
    c.On("ListAnimalFacts", mock.MatchedBy(reqSlothFacts)).
        Return(&page2, nil).
        Once()

    favSnack, err := getSlothsFavoriteSnack(c)
    if err != nil {
        t.Fatalf("got error getting sloths' favorite snack: %v", err)
    }

    if favSnack != "hibiscus flowers" {
        t.Errorf(
            "expected favorite snack to be hibiscus flowers, got %s",
            favSnack,
        )
    }

    c.AssertNumberOfCalls(t, "ListAnimalFacts", 2)
}

Here's what happens in our test:

Outside of our test, we define the function reqSlothFacts we'll pass into MatchedBy. We match the word "sloth", as well as a couple other ways to describe a sloth just for fun: "lemur: caffeine-free edition" and "descendants of the giants who made today's avocados happen" (giant ground sloths 10,000 years ago ate what avocados looked like 10,000 years ago, so next time you have some guac, thank a sloth). We also define two pages of search results.
Inside our TestGetSlothsFavoriteSnackOnPage2, we define two calls to ListAnimalFacts similar to before, but this time instead of passing in an exact query, we pass in mock.MatchedBy(reqSlothFacts) to say "a call to ListAnimalFacts matches this call to Mock.On() if its argument, passed into reqSlothFacts, returns true".
On each call to Mock.On(), we add on a call to .Once(). When we call getSlothsFavoriteSnack, the first time we get back the results we defined with page1 and the second time we get back the results we defined with page2.
Then we run the test the same way as before, but at the tail end, we run AssertNumberOfCalls to show that we really did call ListAnimalFacts twice, rather than getting the results on the first page.

By the way, in addition to MatchedBy, if you don't need such fine-grained control over the arguments you pass in, there also is mock.Anything that you can pass into Mock.On to match any argument at all.

For example, a lot of API clients these days take in a context.Context, which is often in charge of things like traces with observability tools or giving a request a deadline to finish with context.WithDeadline. But often that does not affect the headers and body of our request or response. So if the context isn't a focal point of what you're testing, you can mock it out with Anything. For example if our client's interface looked like this:

type ZooClient interface {
    ListAnimalFacts(
        ctx context.Context,
        q AnimalFactsQuery,
    ) (*AnimalFactsResponse, error)
}

You would do your Mock.On call like this:

  c := newMockClient()
  c.On(
      "ListAnimalFacts",
+     mock.Anything,
      firstPageAPIReq,
  ).Return(&AnimalFactsResponse{

🧰 Testify Mock is just one tool for testing your web apps

As you can see, Testify Mock is a convenient tool for testing code that needs to make an API call, particularly when it comes to HTTP responses like 500 errors that you're not suppposed to consistently be getting.

But there's another way we could have tested all these API interactions without having to rely on the real API:

Make an httptest.Server that has HTTP handlers to mimic the API endpoints we're testing, deserializing requests and serializing responses
Point the HTTP implementation of the API client at that server and run tests using that implementation
Do assertions on the mock responses you get back

Both the httptest approach and Testify Mock approach are valid ways to test the code. Furthermore, while both kinds of mocks are useful themselves, that's not to say testing against the real API isn't itself beneficial. By testing against the very same servers your code talks to in production, you can sniff out server behaviors your dev team wasn't aware of from just reading the server's API documentation. While this isn't a hard and fast rule, my personal style for when to use which kind of Go test is:

When I'm the one implementing the client to the API I'm working with, I would go with the httptest Server approach for its unit tests. Part of the client's job is to serialize and deserialize Go types, so the thing being tested, so the focal point of the test is that the headers, request, and response bodies are correct.
For code that's built on top of a client, such as getSlothsFavoriteSnack, my go-to is Testify Mock. Either I wrote and unit-tested the HTTP implementation of the client or the open source developer I'm go getting the client from did. So now the focal point of a test is the question "given that the API client works as expected, does my code do the right thing with the response it gets back"?
- However if you got the client as a dependency but it doesn't have test coverage for the API calls you're making, it might still be a good idea to test using the httptest.Server approach if its implementation allows you to point it at a custom httptest Server URL.
Finally, for testing that your app works end-to-end, having your continuous integration platform run a nightly build that runs tests against the real API will help you detect bugs and unexpected behaviors your mocks might not have taken into account.
- ⚠️WARNING⚠️: Chances are, the server you're talking to in this nightly build will need to obtain and use some kind of API key or authentication token. BE CAREFUL configuring your continuous integration so that that authentication doesn't get stolen. In particular, do not put the key/token directly in your code.

Happy testing!

Mocks in Go tests with Testify Mock

Andy Haskell — Mon, 24 Oct 2022 14:07:47 +0000

In parts 1-3 of this tutorial series, we saw how you can use Go to write automated tests. Go's testing is very conducive to giving test coverage to a lot of your codebase's functionality. However, there's one area in particular where it's harder to do automated tests: code that is nondeterministic.

When I say nondeterministic code, I am talking about code where you don't have total control over the code's logic and output. This can be things like:

🧮 Code that uses pseudorandom number generators, like math/rand
💻 Web API calls and their response payloads, or errors
⏰ The current time returned by time.Now

Luckily, one tool that helps with testing nondeterministic code, is the mock package of the popular Testify testing framework, which you can use for mocking out these API calls.

For this tutorial, we'll look at how to mock out code that uses math/rand, then in a follow-up post, we'll mock out a fake web API client to see how to use Testify Mock in more complex scenarios.

Prerequisites for this tutorial are familiarity with the basics of writing and running a Go test, which the first tutorial in this series covers.

🎰 Getting some nondeterministic code and the Testify Mock package

Probably the easiest nondeterministic code to get ahold of is the math/rand package, so for this tutorial, we'll look at how we would use Testify Mock to test code that uses randomness. We'll make a function that takes in an integer, and integer-divides (no decimal point) it by a number between 1 and 10.

package main

import (
    "math/rand"
)

func divByRand(numerator int) int {
    return numerator / int(rand.Intn(10))
}

Pretty simple function, but since we called rand.Intn, which takes in a maximum value and returns a random integer up to that maximum, divByRand as a whole is nondeterministic; we have control over the numerator, but not the denominator.

But that's where Testify Mock package comes in; we can make it so in a given test, we do get back the same value for rand.Intn every time.

First let's install Testify Mock with:

go get github.com/stretchr/testify/mock

Now we're ready to use Testify Mock to give divByRand some test coverage!

✨ Using Testify Mock

Now that we've got our nondeterministic code, here's the steps to making it testable with Testify Mock:

Take the nondeterministic piece of functionality and wrap it in a Go interface type.
Write an implementation of the interface that uses Testify Mock.
In the tests, use the mock implementation to select deterministic results of the functions your interface calls.

Besides injecting your mock into your code, the test is otherwise written like any other Go test.

Let's try it out on divByRand, step by step!

1. Take the nondeterministic function calls and wrap them in an interface

For divByRand, the nondeterministic code we're working with is math/rand's Intn function, which takes in an integer and returns another integer. Here's what wrapping that method in an interface looks like:

type randNumberGenerator interface {
    randomInt(max int) int
}

Now that we've got our interface, here's the plain implementation that calls the standard library's rand.Intn.

// our standard-library implementation is an empty
// struct whose randomInt method calls math/rand.Intn
type standardRand struct{}

func (s standardRand) randomInt(max int) int {
    return rand.Intn(max)
}

Now that we've got one interface implementation, we can use that in our divByRand function like this:

  func divByRand(
      numerator int,
+     r randNumberGenerator,
  ) int {
-     return numerator / rand.Intn(10) 
+     return numerator / r.randomInt(10)
  }

We now would call divByRandom in our production code using a function call like divByRandom(200, standardRand{}).

In tests, though, we will instead use a mock implementation of our randNumberGenerator interface, which we'll write in the next section.

2. Write an implementation of the interface that uses Testify Mock

The Testify Mock package's main type is Mock, which handles the logic for mock API calls, such as:

For each method being mocked, keeping track of how many times it was called, and with what arguments.
Providing the coder with a way to specify return values to get back from the mock implementation when specified arguments are passed into given function calls.

We would first set up our mock implementation by embedding a Mock into a struct:

type mockRand struct { mock.Mock }

func newMockRand() *mockRand { return &mockRand{} }

By embedding a Mock, now the mockRand type has the methods for registering an API call that you expect to happen in the tests.

For example, at the beginning of a test that uses the randomNumberGenerator interface, we could call:

var m mockRand
m.On("randomInt", 10).Return(6)

which says "if the number 10 is passed in as the maximum number for this mockRand's randomInt method, then always return the number 6".

In order to be able to use m.On("randomInt", arg) however, we will need to actually give our mockRand a randomInt method. Here's how we would do that:

func (m *mockRand) randomInt(max int) int {
    args := m.Called(max)
    return args.Int(0)
}

We've got two lines of code, let's take a look at what they do. If it seems confusing at first, no worries; it will make more sense when we are actually using this code in a test.

In the first line when randomInt is called, we call Mock.Called to record that it was called with the value passed in for max.
Additionally, m.Called returns an Arguments object, which contains the return value(s) that we specified in the test to be returned if the function gets the given value of max. For example, if we called m.On("randomInt", 20).Return(7) in the test, m.Called(20) would return an Arguments object holding the return value 7.
Finally, to retrieve the return value, in the second line we call args.Int(0), which means "return the zeroeth return value, and it will be of type int".

Note that in addition to Arguments.Int, there's also Bool, String, and Error methods, which give us back the n-th return value in those types. And if you have a return value of another type, you would retrieve it with the Arguments.Get method, which returns an interface{} you would then convert to the type you expect to get back.

3. In the tests, use the mock implementation and feed in results the function returns.

We've got our mockRand type implementing the randomNumberGenerator interface, so it can be passed into divByRand in Go code, including in our tests. The steps of our test now are:

Create an instance of your mock interface implementation.
Specify what results you want back when the mock's methods are called with a given set of arguments using the On and Return methods.
Run the code that's being tested, the standard way you would in a Go test.
Optionally, use methods like Mock.AssertCalled to check that a given method indeed had been called during the test.

Here's what that looks like in code:

package main

import (
    "testing"
)

func TestDivByRand(t *testing.T) {
    // get our mockRand
    m := newMockRand()
    // specify our return value. Since the code in divByRand
    // passes 10 into randomInt, we pass 10 in as the argument
    // to go with randomInt, and specify that we want the
    // method to return 6.
    m.On("randomInt", 10).Return(6)

    // now run divByRand and assert that we got back the
    // return value we expected, just like in a Go test that
    // doesn't use Testify Mock.
    quotient := divByRand(30, m)
    if quotient != 5 {
        t.Errorf("expected quotient to be 5, got %d", quotient)
    }

    // check that randomInt was called with the number 10;
    // if not then the test fails
    m.AssertCalled(t, "randomInt", 10)
}

Run go test -v and you'll get a passing test. But there's a bug in the original implementation of divByRand, so let's find it and give that bug some test coverage!

🐛 Finding and fixing a bug using Testify Mock

We wrote a test that utilizes Testify Mock, so now let's try using it to find a bug!

Since we're dividing by a nondeterministic value, we should have test coverage to make sure we can't accidentally divide by zero.

func TestDivByRandCantDivideByZero(t *testing.T) {
    m := newMockRand()
    m.On("randomInt", int64(10)).Return(int64(0))

    quotient := divByRand(30, m)
    if quotient != 30 {
        t.Errorf("expected quotient to be 30, got %d", quotient)
    }
}

This time around, when we pass 10 into our mockRand's randomInt method, we return 0. So in divByRand, we end up dividing by 0.

Run go test -v and you should get:

--- FAIL: TestDivByRandCantDivideByZero (0.00s)
panic: runtime error: integer divide by zero [recovered]
    panic: runtime error: integer divide by zero

A panic from dividing by zero. Let's fix divByRand method to prevent this:

  func divByRand(n int, r randNumberGenerator) int {
-     return n / r.randomInt(10)
+     denominator := 1 + int(r.randomInt(10))
+     return n / denominator
  }

Now that we're passing 9 instead of 10 into our call to randomInt, we do need to update our test coverage to register a call to randomInt(9) instead of randomInt(10), and for TestDivByRand, we need to return 5 instead of 6 since in divByRand we add 1 to the returned value.

  func TestDivByRand(t *testing.T) {
      var m mockRand
-     m.On("randomInt", 10).Return(6)
+     m.On("randomInt", 10).Return(5)

Run go test -v one more time and you should get...

=== RUN   TestDivByRand
--- PASS: TestDivByRand (0.00s)
=== RUN   TestDivByRandCantDivideByZero
--- PASS: TestDivByRandCantDivideByZero (0.00s)
PASS
ok      github.com/andyhaskell/testify-mock 0.114s

Passing tests!

We've looked at how to use Testify Mock to write test coverage for randomness. In the next tutorial, we'll take a look at using Testify Mock to mock out a web API call.

Processing user input in Bubble Tea with a menu component

Andy Haskell — Sun, 23 Oct 2022 21:25:24 +0000

In the last tutorial, we did a "hello world" app, and it processed just a bit of user input ("press Ctrl+C to exit").

But we didn't really get a feel for actually using user input to change the model's data, and in turn change what we see in the app. So in this tutorial, we're going to create a menu component that lets us move between buttons.

📝 Defining our data

The first thing we need for any Bubble Tea component is the data our model is in charge of. If you recall, in our simplePage model, the data was just the text we were displaying:



type simplePage struct { text string }

In our menu, what we need to do is:

Display our options
Show which option is selected
Additionally, let the user press the enter to go to another page. But we'll add that in a later tutorial.
- For now, we can still make an onPress function passed in that tells us what we do if the user presses enter.

So our model's data will look like this; if you're following along, write this in a file named menu.go.



type menu struct {
    options       []menuItem
    selectedIndex int
}

type menuItem struct {
    text    string
    onPress func() tea.Msg
}

A menu is made up of menuItems, and each menuItem has text and a function handling pressing enter. In this tutorial we'll just have the app toggle between all-caps and all-lowercase so it's at least doing something.

It returns a tea.Msg because that's we're able to change the data in response to this user input. We'll see why in the next section, when we're implementing the Model interface.

🧋 Implementing the Model interface

If you recall, for us to use our model as a UI component, it needs to implement this interface:



type Model interface {
    Init() Cmd
    Update(msg Msg) (Model, Cmd)
    View() string
}

First let's write the Init function.



func (m menu) Init() tea.Cmd { return nil }

Again, we still don't have any initial Cmd we need to run, so we can just return nil.

For the View function, let's make an old-school menu with an arrow to tell us which item is currently selected.



func (m menu) View() string {
    var options []string
    for i, o := range m.options {
        if i == m.selectedIndex {
            options = append(options, fmt.Sprintf("-> %s", o.text))
        } else {
            options = append(options, fmt.Sprintf("   %s", o.text))
        }
    }
    return fmt.Sprintf(`%s

Press enter/return to select a list item, arrow keys to move, or Ctrl+C to exit.`,
    strings.Join(options, "\n"))
}

As mentioned in the last tutorial, one of the things that makes Bubble Tea really learnable is that the display for your UI is basically one big string. So in menu.View we make a slice of strings where the selected option has an arrow and the non-selected options have leading spaces. Then we join them all together and add our contols to the bottom.

Finally, let's write our Update method to handle user input.



func (m menu) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg.(type) {
    case tea.KeyMsg:
        switch msg.(tea.KeyMsg).String() {
        case "ctrl+c":
            return m, tea.Quit
        case "down", "right", "up", "left":
            return m.moveCursor(msg.(tea.KeyMsg)), nil
        }
    }
    return m, nil
}

func (m menu) moveCursor(msg tea.KeyMsg) menu {
    switch msg.String() {
    case "up", "left":
        m.selectedIndex--
    case "down", "right":
        m.selectedIndex++
    default:
        // do nothing
    }

    optCount := len(m.options)
    m.selectedIndex = (m.selectedIndex + optCount) % optCount
    return m
}

The Update method is the most complex part of this app, so let's break that down.



case "ctrl+c":
    return m, tea.Quit

Like before, we're handling the KeyMsg type, and we're the Ctrl+C keypress to quit the app by returning the Quit cmd.



case "down", "right", "up", "left":
    return m.moveCursor(msg.(tea.KeyMsg)), nil

For the arrow keys, though, we use a helper function, moveCursor, which returns an updated model.



func (m menu) moveCursor(msg tea.KeyMsg) menu {
    switch msg.String() {
    case "up", "left":
        m.selectedIndex--
    case "down", "right":
        m.selectedIndex++
    default:
        // do nothing
    }

    optCount := len(m.options)
    m.selectedIndex = (m.selectedIndex + optCount) % optCount
    return m
}

The up and left KeyMsg strings serve as our "navigate up" keys, and the down and right ones navigate us down, decrementing and incrementing m.selected.

Then, we use the mod operator to ensure that m.selected is one of the indices of our options.

Finally, with the model updated, moveCursor returns the model that in turn is returned by Update, and the new model ultimately gets processed by our View method.

Before we move on to processing the enter key though, we should see our app run. So let's put our new menu component into a main function and run it.



func main() {
    m := menu{
        options: []menuItem{
            menuItem{
                text: "new check-in",
                onPress: func() tea.Msg { return struct{}{} },
            },
            menuItem{
                text: "view check-ins",
                onPress: func() tea.Msg { return struct{}{} },
            },
        },
    }

    p := tea.NewProgram(m)
    if err := p.Start(); err != nil {
        panic(err)
    }
}

For now, onPress is just a no-op that returns an empty struct. Now, let's run our app.



go build
./check-ins

You should see something like this:

Cool! Now the menu can toggle what's selected! Now let's handle that user input.

✅ Handling the enter key and seeing what the tea.Cmd type actually does

So far, we haven't really taken a close look at the tea.Cmd type. It's one of the two return values for the Update method, but we've only used it so far to exit the app. Let's take a closer look at its type signature.



type Cmd func() tea.Msg

A Cmd is some sort of function that does some stuff, and then gives us back a tea.Msg. That function can be time passing, it can be I/O like retrieving some data, really anything goes! The tea.Msg in turn gets used by our Update function to update our model and finally our view.

So handling a user pressing the enter key, and then running an arbitrary onPress function, is one such way to use a Cmd. So let's start with an enter button handler.



  case tea.KeyMsg:
      switch msg.(tea.KeyMsg).String() {
      case "q":
          return m, tea.Quit
      case "down", "right", "up", "left":
          return m.moveCursor(msg.(tea.KeyMsg)), nil
+     case "enter", "return":
+         return m, m.options[m.selectedIndex].onPress
      }

Notice that when the user presses enter, we return the model, unchanged, but we also return the selected item's onPress function. If you recall when we defined the menuItem type, the type of its onPress field was func() tea.Msg. In other words, that exactly matches the Cmd type alias!

There's one other thing we need to do inside the Update method though. Right now, we're only handling the tea.KeyMsg type. The type we're returning for toggling the selected item's capitalization will be a brand new type ot tea.Msg, so we need to define it, and then add a case to our Update method for it. First, let's define the struct.



type toggleCasingMsg struct{}

We don't need any data to be passed in, so our Msg is just an empty struct; if you recall, the tea.Msg type is just an empty interface, so we can have a Msg contain as much or as little data as we need.

Now back in the Update method, let's add a case for toggleCasingMsg!

First add the method toggleSelectedItemCase



func (m menu) toggleSelectedItemCase() tea.Model {
    selectedText := m.options[m.selectedIndex].text
    if selectedText == strings.ToUpper(selectedText) {
        m.options[m.selectedIndex].text = strings.ToLower(selectedText)
    } else {
        m.options[m.selectedIndex].text = strings.ToUpper(selectedText)
    }
    return m
}

Then add it to the Update method.



  func (m menu) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
      switch msg.(type) {
+     case toggleCasingMsg:
+         return m.toggleSelectedItemCase(), nil
      case tea.KeyMsg:
          // our KeyMsg handlers here

On a toggleCasingMsg, we update the casing of the selected menu item, and then return the updated model.

Finally, in app.go, let's use our toggleCasingMsg



  menuItem{
      text:    "new check-in",
-     onPress: func() tea.Msg { return struct{}{} },
+     onPress: func() tea.Msg { return toggleCasingMsg{} },
  },
  menuItem{
      text:    "view check-ins",
-     onPress: func() tea.Msg { return struct{}{} },
+     onPress: func() tea.Msg { return toggleCasingMsg{} },
  },

Now let's try our app out!



go build
./check-ins

The app should now look like this:

Note, by the way, that at this stage of the app, this isn't the only way we could have processed enter; we also could have just processed all the toggling entirely in the update function, rather than having to process it with a Cmd. The reason I chose to use a Cmd were:

To show a simple use case for a non-Quit Cmd in Bubble Tea
By using a Cmd, we can pass arbitrary event handler functions into our components, a similar pattern if you've coded in React.

Next up, we've got a menu, but it's not very flashy just yet. In the next tutorial, we'll see how to use Bubble Tea to make our app look cool; first by hand, then with Bubble Tea's CSS-like Lip Gloss package!

Intro to Bubble Tea in Go

Andy Haskell — Sun, 23 Oct 2022 21:23:52 +0000

Doing stuff in the command line is cool and can make you feel like you're the hero in a hacker movie. But it can also feel old-school with monochromatic avalanches of text, or intimidating with all the command line flags and dollar sign prefixes and different ways to break things without warning.

But the command line isn't the only way to use your terminal, there's also TUIs, terminal user interfaces, which give a more user-friendly feel to your program. I really like TUIs because they feel like the new and the old at the same time. And in Go, lately the Bubble Tea library, and all of Charm Bracelet's other tools, has been getting a lot of attention for making it easy to make TUIs.

The advantages of Bubble Tea that have jumped out at me so far are:

Uses the Elm architecture that's shared with browser UI frameworks, so if you've already done some React, Vue, or Elm, it will feel familiar
The Elm architecture isn't just familiar for modern frontend devs, it's a great way to organize UI code, so it's conducive to building starting your app simple and growing its logic in a manageable way
Because it's in Go, the language's consistent syntax is conducive to learning by reading other people's code

In this series, I'm going to be building a basic TUI app from the ground up for logging what you've been learning in code each day if you're doing a program like #100Devs or one of the ones in the #100DaysOfCode family. At the time I'm writing this it's not finished yet, so each tutorial will be about looking at specific concepts. The approximate roadmap is going to be:

🐣 Writing a simple hello world app and seeing how its architecture works
📝 Building our first real Bubble Tea component, a menu
✨ Making our menu look cool with some styling, using the CSS-like Lipgloss library
🚇 Adding routing to our app to display different pages
🫧 Using Bubble Tea components other people have made, using the Bubbles library
📝 Saving our check-ins to a JSON file

So get your terminal ready, and a boba-sized straw because without further ado it's time to jump into Bubble Tea!

🚧 Writing our first basic app

As a first step, we're going to make a "hello world" app in Bubble Tea that you exit by pressing Ctrl+C, which will also introduce us to each part of a Bubble Tea app.

First, in a new directory titled "code-journal", run:



go mod init
go get github.com/charmbracelet/bubbletea

Then, create a file called app.go and add the following code:



package main

import (
    tea "github.com/charmbracelet/bubbletea"
)

func main() {
    p := tea.NewProgram(
        newSimplePage("This app is under construction"),
    )
    if err := p.Start(); err != nil {
        panic(err)
    }
}

Then, let's make another file called simple_page.go that contains our first UI, a simple page that just displays some text:


 go
package main

import (
    "fmt"
    "strings"

    tea "github.com/charmbracelet/bubbletea"
)

// MODEL DATA

type simplePage struct { text string }

func newSimplePage(text string) simplePage {
    return simplePage{text: text}
}

func (s simplePage) Init() tea.Cmd { return nil }

// VIEW

func (s simplePage) View() string {
    textLen := len(s.text)
    topAndBottomBar := strings.Repeat("*", textLen + 4)
    return fmt.Sprintf(
        "%s\n* %s *\n%s\n\nPress Ctrl+C to exit",
        topAndBottomBar, s.text, topAndBottomBar,
    )
}

// UPDATE

func (s simplePage) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg.(type) {
    case tea.KeyMsg:
        switch msg.(tea.KeyMsg).String() {
        case "ctrl+c":
            return s, tea.Quit
        }
    }
    return s, nil
}

Before we break down the code, let's run it and see what it does. In your terminal, run:



go build
./code-journal

and you should see something like this:

Cool! You've got your first Bubble Tea app running. Now let's take a closer look at the code.

🧋 Model is the main interface of Bubble Tea

The main function starts the program by creating a new program with the simplePage model.



func main() {
    p := tea.NewProgram(
        newSimplePage("This app is under construction"),
    )
    if err := p.Start(); err != nil {
        panic(err)
    }
}

We call tea.NewProgram, whose signature is:



func NewProgram(initialModel Model) *Program

and then calling that program's Start method starts our app. But what is the initialModel?

Model is the main interface of Bubble Tea. It has three methods:



type Model interface {
    Init() Cmd
    Update(msg Msg) (Model, Cmd)
    View() string
}

The Init method is called when the app starts, returning a tea.Cmd. A Cmd is more or less "stuff happening behind the scenes" like loading data, or time flowing. But for the current tutorial, we don't have any background stuff, so our init method just returns nil.



func (s simplePage) Init() tea.Cmd { return nil }

Next up, we've got the View method. One of the cool abstractions of Bubble Tea is that your whole UI's display is a string! And View is where you make that string.



func (s simplePage) View() string {
    textLen := len(s.text)
    topAndBottomBar := strings.Repeat("*", textLen + 4)
    return fmt.Sprintf(
        "%s\n* %s *\n%s\n\nPress Ctrl+C to exit",
        topAndBottomBar, s.text, topAndBottomBar,
    )
}

So we put the text of our simplePage in a box made of asterisks, with a message at the bottom saying "Press Ctrl+C to exit"

But we can't exit our app if it doesn't handle user input, so that's where our Update method comes in.



func (s simplePage) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg.(type) {
    case tea.KeyMsg:
        switch msg.(tea.KeyMsg).String() {
        case "ctrl+c":
            return s, tea.Quit
        }
    }
    return s, nil
}

The Update method takes in a tea.Msg and returns a new tea.Model and sometimes a tea.Cmd (like if an action results in retrieving some data or a timer going off).

A tea.Msg's type signature is



type Msg interface {}

So it can be any type and carry as much or as little data as you need. It's sort of like a browser event in JavaScript if you've done frontend there; a timer event doesn't carry any data, a click event tells you what clicked on, etc.

The kind of message we're processing is tea.KeyMsg, which represents keyboard input. We're checking if the user pressed Ctrl+C, and if so, we return the tea.Quit command, which is of the type tea.Cmd and tells Bubble Tea to exit the app.

For any other kind of input though, we don't do anything. We just return the model as-is. If we were doing something though like UI navigation, though, we would change some fields on the Model and then return it, causing the UI to update. And that's what we're going to see in the next tutorial where we make a menu component!

#WebDevSampler challenge - My answers in Go

Andy Haskell — Fri, 12 Aug 2022 00:48:08 +0000

As a first time doing the #WebDevSampler challenge, I used Go, which is a popular backend language, as well as the language I have been coding in professionally for seven years. Ahead are my answers to the 11 exercises in the sampler, which are:

(1) Get an HTTP server up and running, serving an endpoint that gives the HTTP response with a message like "hello world!".
- Concept demonstrated: starting an HTTP server and processing an HTTP request.
(2) Give that HTTP response as HTML, with Content-Type text/html
- Concept demonstrated: editing the HTTP response using response headers
(3) Adding another endpoint/route on your HTTP server, such as an /about.html page
- Concept demonstrated: serving more than one HTTP endpoint
(4) Serving an endpoint with an image or webpage in your file system
- Concept demonstrated: serving content from a file system
(5) Route to an endpoints using more complex route like /signup/my-name-is/:name, for example if I send a request to /signup/my-name-is/Andy I would get back "You're all signed up for the big convention Andy!"
- Concept demonstrated: Parameterized routing
(6) Write and run an automated test for your HTTP parameterized endpoint
- Concept demonstrated: Automated testing with an HTTP endpoint in one of your language's testing CLI tools.
(7) Escape HTML tags in your endpoint. For example, /signup/my-name-is/<i>Andy should be sanitized so you DON'T display your name in italics
- Concept demonstrated: Basic input sanitization
(8) Serialize an object/struct/class to some JSON and serve it on an endpoint with a Content-Type: application/json
- Concept demonstrated: JSON serialization, which is done a lot creating backend APIs
(9) Add a POST HTTP endpoint whose input is of Content-Type application/json, deserialize it to an object/struct/class, and then use some part of the object to produce some part of the HTTP response.
- Concept demonstrated: JSON deserialization
(10) Now have that POST endpoint save the content to some database (MongoDB, Postgres, Cassandra, any database you want)
- Concept demonstrated: Database input
(11) Now make a GET endpoint that retrieves a piece of data from the database
- Concept demonstrated: Database retrieval

The tools I used for doing this challenge were:

The Go standard library
Go's built-in testing command for doing automated test coverage
Gorilla Mux for parameterized HTTP routing
SQLite and mattn's SQLite package for the database problems

Now, onward to the answers!

(1) Get an HTTP server up and running, serving an endpoint that gives the HTTP response with a message like "hello world!".

Go code

package main

import (
    // Go's standard library package for HTTP clients and servers
    "net/http"
)

func main() {
    // make an http.ServeMux, a Go standard library object that
    // routes HTTP requests to different endpoints
    rt := http.NewServeMux()

    // Make a catch-all endpoint for all requests going into the
    // server. When the endpoint is hit, we run the function passed
    // in to process the request.
    rt.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        // We have the ResponseWriter write the bytes of the string
        // "Hello world!"
        w.Write([]byte("Hello world!"))
    })

    // create a new server and run it with ListenAndServe to take
    // HTTP requests on port 1123
    s := http.Server{Addr: ":1123", Handler: rt}
    s.ListenAndServe()
}

Starting the program

Run go run main.go, or use go install and run the installed binary
Go to http://localhost:1123 in a browser or in a program like cURL. You should see the text "hello world!"

(2) Give that HTTP response as HTML, with Content-Type `text/html`

Go code

rt.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    // Add the header "Content-Type: text/html"
    w.Header().Set("Content-Type", "text/html")

    // Add some HTML <h1> tags to the hello world response. The
    // browser, seeing the response is Content-Type: text/html,
    // will display the response as a big header.
    w.Write([]byte("<h1>Hello world!</h1>"))
})

Starting the program

Compile and start the server again, and refresh http://localhost:1123
The response should now be displayed as a webpage

(3) Add another endpoint/route on your HTTP server, such as an `/about.html` page

Go code

// naming the route "/about" makes it so when a request is sent to
// http://localhost:1123/about, the about page is served instead of
// the hello world page
rt.HandleFunc("/about", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/html")

    w.Write([]byte(`
      <!DOCTYPE html>
      <html>
        <head>
          <title>About us</title>
        </head>
        <body>
          <h1>About us</h1>
          <p>We've got a website!</p>
        </body>
      </html>
    `))
})

Starting the program

Compile and start the server again
Go to http://localhost:1123/about. You should now see your about page.

(4) Serving an endpoint with an image or webpage in your file system

Preliminary steps

Make a directory inside the directory where main.go is, named "images"
Save a JPEG image in that images directory named "gopher.jpg"

Go code

// We are using Handle, not HandleFunc, because we're passing
// in an object of type http.Handler, not a function
rt.Handle(
    "/images/",
    // StripPrefix chops the prefix, in this case "/images/",
    // off of the HTTP request's path before passing the
    // request to the http.FileServer
    http.StripPrefix(
        "/images/",
        // create a FileServer handler that serves files in
        // your "images" directory
        http.FileServer(http.Dir("images")),
    ),
)

Starting the program

Compile and start the server again
Go to http://localhost:1123/images/gopher.jpg. You now should see your gopher.jpg file

(5) Route to an endpoints using more complex route like /signup/my-name-is/:name

Preliminary steps

For this, one, we'll use the Gorilla Mux library, since that is one of the most popular HTTP routing libraries in Go.

Set up a go.mod file with go mod init. go mod is Go's built-in package manager, and it is where your project's dependencies are listed, similar to package.json in Node.js.
Run go get github.com/gorilla/mux

Go code

First add Gorilla Mux to your imports

import (
    // fmt is a string formatting package in Go
    "fmt"
    "net/http"

    // Now we're importing the Gorilla Mux package in addition to
    // net/http
    "github.com/gorilla/mux"
)

Then at the start of main, replace the ServeMux with a Gorilla Mux Router and add your parameterized endpoint to it

func main() {
    // now instead of a ServeMux, we're using a Gorilla Mux router
    rt := mux.NewRouter()

    // Our new parameterized route
    rt.HandleFunc(
        // make a parameter in the request path that Gorilla
        // recognizes with the string "name"
        "/signup/my-name-is/{name}",
        func(w http.ResponseWriter, r *http.Request) {
            // the route parameters on the request are parsed
            // into a map[string]string
            name := mux.Vars(r)["name"]

            w.Header().Set("Content-Type", "text/html")
            w.Write([]byte(fmt.Sprintf(
                // use the route parameter in the HTTP response
                "<h1>You're all signed up for the big convention %s!</h1>", name,
            )))
        },
    )

    // Our existing endpoints mostly stay the same as before
}

Finally, update the format of the images directory endpoint to use PathPrefix, which is what you use for path prefixes in Gorilla Mux as opposed to Handle("/path/", handler)

rt.PathPrefix("/images/").Handler(
    http.StripPrefix(
        "/images/", http.FileServer(http.Dir("images")),
    ),
)

Starting the program

Compile and start the server again
Go to http://localhost:1123/signup/my-name-is/YOUR_NAME. You now should get an HTML response saying you're signed up

(6) Write an automated test for your HTTP parameterized endpoint

Preliminary steps

First, take the logic for setting up our Mux router and move it to its own function

func handleSignup(w http.ResponseWriter, r *http.Request) {
    name := mux.Vars(r)["name"]

    w.Header().Set("Content-Type", "text/html")
    w.Write([]byte(fmt.Sprintf(
        "<h1>You're all signed up for the big convention %s!</h1>", name,
    )))
}

// The router function is pretty much the same as the main
// function as of the last exercise, from when rt is declared
// to when we declared the last handler in the router.
func router() http.Handler {
    rt := mux.NewRouter()

    rt.HandleFunc("/signup/my-name-is/{name}", handleSignup)
    // not shown: The other endpoints' handlers

    // mux.Router, the type of rt, implements the http.Handler
    // interface, which is in charge of handling HTTP requests
    // and serving HTTP responses.
    return rt
}

Now replace the body of main with:

func main() {
    // create a new server and run it with ListenAndServe to take
    // HTTP requests on port 1123
    s := http.Server{Addr: ":1123", Handler: router()}
    s.ListenAndServe()
}

Then, make a new file named app_test.go

Go code (in app_test.go)

package main

import (
    // Standard library package for working with I/O
    "io"
    // Standard library testing utilities for Go web apps
    "net/http/httptest"
    // Standard library URL-parsing package
    "net/url"
    // Standard library testing package
    "testing"
)

// Functions whose name start with Test and then a capital
// letter and take in a testing.T object are run by the
// `go test` subcommand
func TestSignup(t *testing.T) {
    // A ResponseRecorder is the httptest implementation of
    // http.ResponseWriter, that lets us see the HTTP response
    // it wrote after running an HTTP handler function
    w := httptest.NewRecorder()

    // convert a string to a *url.URL object
    reqURL, err := url.Parse("http://localhost:1123/signup/my-name-is/Andy")
    if err != nil {
        // if parsing the URL fails, have the test fail
        t.Fatalf("error parsing URL: %v", err)
    }

    // set up our HTTP request, which will be to the endpoint
    r := &http.Request{URL: reqURL}

    // send the request to the HTTP server by passing it and the
    // ResponseWriter to mux.Router.ServeHTTP(). The result of
    // that HTTP call is stored in the ResponseRecorder.
    router().ServeHTTP(w, r)

    res := w.Result()
    // convert the response stored in res.Body to bytes and check
    // that we got back the response we expected.
    body, err := io.ReadAll(res.Body)
    if err != nil {
        t.Fatalf("error retrieving response body: %v", err)
    }
    bodyStr := string(body)
    expected := `<h1>You're all signed up for the big convention Andy!</h1>`
    if bodyStr != expected {
        t.Errorf("expected response %s, got %s", expected, bodyStr)
    }
}

Running the test

From the directory the Go files are in, run go test -v
Observe the test passing. If you change the text the sign-up endpoint serves, then the test should now fail.

(7) Escape HTML tags in your endpoint.

Go code (main.go)

First import the net/html package

import (
    // standard library package for working with HTML
    "html"
    "net/http"

    "github.com/gorilla/mux"
)

Then update handleSignup to call EscapeString. In a real production app, we'd be doing more advanced sanitization of user data than this and probably rendering our HTML using a templating library that has sanitization built-in in order to catch more edge cases with malicious input, but EscapeString handles sanitizing HTML characters as a very simple demonstration of input sanitization.

func handleSignup(w http.ResponseWriter, r *http.Request) {
    name := mux.Vars(r)["name"]
    // we use EscapeString to escape characters that are used in
    // HTML syntax. For example, the character < becomes &lt; and
    // > becomes &gt;
    name = html.EscapeString(name)

    // rest of the endpoint stays the same
    w.Header().Set("Content-Type", "text/html")
    w.Write([]byte(fmt.Sprintf(
        "<h1>You're all signed up for the big convention %s!</h1>", name,
    )))
}

Go test code (main_test.go)

func TestSignupHTMLEscape(t *testing.T) {
    w := httptest.NewRecorder()

    // convert a string to a *url.URL object, this time with
    // some HTML in it that should be escaped
    urlString := "http://localhost:1123/signup/my-name-is/<i>Andy"
    reqURL, err := url.Parse(urlString)
    if err != nil {
        // if parsing the URL fails, have the test fail
        t.Fatalf("error parsing URL: %v", err)
    }

    // run ServeHTTP just like before
    r := &http.Request{URL: reqURL}
    router().ServeHTTP(w, r)

    res := w.Result()
    body, err := io.ReadAll(res.Body)
    if err != nil {
        t.Fatalf("error retrieving response body: %v", err)
    }

    // Expect that we thwarted the HTML injection attempt
    bodyStr := string(body)
    expected := `<h1>You're all signed up for the big convention &lt;i&gt;Andy!</h1>`
    if bodyStr != expected {
        t.Errorf("expected response %s, got %s", expected, bodyStr)
    }
}

Running the test

From the directory the Go files are in, run go test -v
Observe the test passing. If you comment out the EscapeString call, then the test should now fail.

Running the server

Compile and start the server again
Go to http://localhost:1123/signup/my-name-is/<i>YOUR_NAME. You now should NOT get any italicized text since the <i> tag was escaped.

(8) Serialize an object/struct/class to some JSON and serve it on an endpoint with a `Content-Type: application/json`

Go code (near top of main.go)

First, import encoding/json, Go's standard library package for serializing objects to JSON

import (
    // Go's standard library for JSON serialization
    "encoding/json"
    "net/html"
    "net/http"
)

Then define this struct and HTTP endpoint

// Define a type with JSON serialization specified by JSON
// Go struct tags
type animalFact struct {
    AnimalName string `json:"animal_name"`
    AnimalFact string `json:"animal_fact"`
}

// add this function into the "router" function
func sendAnimalFact(w http.ResponseWriter, r *http.Request) {
    fact := animalFact{
        AnimalName: "Tree kangaroo",
        AnimalFact: "They look like teddy bears but have a long"+
                        " tail to keep their balance in trees!",
    }
    // Set the Content-Type for the response to application/json
    w.Header().Set("Content-Type", "application/json")

    // load the ResponseWriter into a JSON encoder, and then by
    // calling that Encoder's Encode method with a pointer to the
    // animalFact struct, the ResponseWriter will write the struct
    // as JSON.
    if err := json.NewEncoder(w).Encode(&fact); err != nil {
        // if serializing the response fails, then return a
        // 500 internal server error response with the error
        // message "error serializing response to JSON".
        // If the serialization succeeds though, we're all
        // set and the HTTP response is already sent.
        w.WriteHeader(http.StatusInternalServerError)
        w.Write([]byte(`{"error": "couldn't serialize to JSON"}`))
    }
}

Finally, add the animal fact to the router function

rt.HandleFunc("/animal-fact", sendAnimalFact)

Running the server

Compile and start the server again
Go to http://localhost:1123/animal-fact. You should get your animal fact in JSON.

(9) Add a POST HTTP endpoint whose input is of Content-Type `application/json`, deserialize it to an object/struct/class, and then use some part of the object to produce some part of the HTTP response.

Go code (near top of main.go)

First, define a signup struct, its JSON serialization using Go struct tags, and an endpoint to handle a JSON payload

import (
    // Go's standard library for JSON serialization
    "encoding/json"
    "net/html"
    "net/http"

    "github.com/gorilla/mux"
)

// Define a type with JSON serialization specified by JSON
// Go struct tags. For example, `json:"days_signed_up_for"`
// indicates that the DaysSignedUpFor field should be
// serialized as days_signed_up_for, not DaysSignedUpFor
type signup struct {
    Name            string `json:"name"`
    DaysSignedUpFor int    `json:"days_signed_up_for"`
}

// add this function into the "router" function
func handleJSONSignup(w http.ResponseWriter, r *http.Request) { 
    // load the request's Body into a JSON Decoder, and then by
    // calling that Decoder's Decode method with a pointer to the
    // signup struct,
    var s signup 
    if err := json.NewDecoder(r.Body).Decode(&s); err != nil {
        // if deserializing the response fails, then return a
        // 400 Bad Request header and the error message
        // "invalid JSON payload"
        w.WriteHeader(http.StatusBadRequest)
        w.Write([]byte("invalid JSON payload"))
        return
    }

    // use the signup in the response body
    name := html.EscapeString(s.Name)
    days := s.DaysSignedUpFor
    msg := fmt.Sprintf(
        "You're all signed up %s! Have a great %d days at the big convention!",
        name, days,
    )

    // NOTE: in a real production endpoint, if we're taking
    // in a JSON payload we'd probably send a JSON response
    // rather than plain text
    w.Write([]byte(msg))
}

Finally, in the router function, add our handleJSONSignup endpoint

rt.Methods(http.MethodPost).Path("/signup").HandlerFunc(handleJSONSignup)

Running the server

Compile and start the server again
Send a request to the POST signup endpoint with your HTTP client. For example, in cURL, that would look like: curl -XPOST http://localhost:1123/signup --data '{"name": "YOUR_NAME", "days_signed_up_for": 3}'. You should now see a response indicating how many days you're signed up for.

(10) Save the input of your POST request to a database

Preliminary steps to using my implementation

In the interest of simplicity, we will use SQLite as our database. If we were developing a big web app and planning on the site getting really popular with tons of people wanting data from the database at the same time, we might instead opt for a database like Postgres or MongoDB.

Install SQLite and add it to your computer's path
Open SQLite's command-line tool from the folder you've been coding the Sampler in. The command to do so is sqlite3.
Create your SQLite database with the command .open website.db.
Create your database table with the command CREATE TABLE signups (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, days_signed_up_for INTEGER);

Now we have a database table to store sign-ups! Now for Go to be able to talk to SQLite, or any SQL database with the Go standard library's database/sql package, we need a database driver for the database we're using. We can get the one for SQLite using

go get github.com/mattn/go-sqlite3

Now we're ready to use the actual code.

Go code

First in main.go, import database/sql, Go's standard library package for working with SQL databases, and underscore-import go-sqlite3 so that database/sql registers the SQLite Go database driver. With that underscore import, your Go code is now able to talk to SQLite databases.

import (
    // Go's standard library for JSON serialization
    "database/sql"
    "encoding/json"
    "fmt"
    "html"
    "net/http"

    "github.com/gorilla/mux"
    // register the database driver for SQLite
    _ "github.com/mattn/go-sqlite3"
)

Then, define an object for interacting with our signups database table. This is so that the logic for interacting with the database is not intertwined with the logic for serving the endpoint, making the code easier to test and harder to get unexpected bugs with.

// signupsDB centralizes the logic for storing signups in
// SQLite.
type signupsDB struct{ db *sql.DB }

func newSignupsDB(filename string) (*signupsDB, error) {
    // Open a database/sql DB for the file path, using the
    // sqlite3 database driver.
    db, err := sql.Open("sqlite3", filename)
    if err != nil {
        return nil, err
    }
    return &signupsDB{db: db}, nil
}

// SQLite syntax to more or less say "insert the values of the
// two question mark parameters into the name and
// days_signed_up_for fields of a new item in the signups table
const insertSignupQuery = `
INSERT INTO signups (name, days_signed_up_for)
VALUES (?, ?)`

func (db *signupsDB) insert(s signup) error {
    // run DB.Exec to insert an item into the database
    result, err := db.db.Exec(
        insertSignupQuery, s.Name, s.DaysSignedUpFor,
    )
    if err != nil {
        return err
    }

    // check that only one item was inserted into the database
    // table
    rowsAffected, err := result.RowsAffected()
    if err != nil {
        return err
    } else if rowsAffected != 1 {
        return fmt.Errorf(
            "expected 1 row to be affected, but %d rows were.",
            rowsAffected,
        )
    }
    return nil
}

Now add an init function for initializing our database. Note that this isn't how we'd set up a database connectioin in a production app, but it's probably the simplest way to do this setup.

// in a real production Go web app, we would be structuring
// our HTTP handlers to be data structures instead of plain
// functions so we aren't relying on global variables, but
// for the sampler we'll just initialize our database in the
// init function and panic if that fails to keep things simple
var db *signupsDB

func init() {
    var err error
    if db, err = newSignupsDB("./website.db"); err != nil {
        panic(fmt.Sprintf(
            "error opening db: %v; can't start the web app", err,
        ))
    }
}

Then add db: struct tags for serializing your object in a database as well as in JSON.

type signup struct {
    Name            string `json:"name",db:"name"`
    DaysSignedUpFor int    `json:"days_signed_up_for",db:"days_signed_up_for"`
}

Finally, in the handleJSONSignup endpoint, add this if statement right before where you serve the HTTP response:

    if err := db.insert(s); err != nil {
        // in a real production web app, we'd look in more
        // detail at the error's value to decide the
        // appropriate status code and error message
        w.WriteHeader(http.StatusInternalServerError)
        w.Write([]byte("error inserting signup"))
        return
    }

Running the server

Compile and start the server again
Send a request to the POST signup endpoint with your HTTP client. For example, in cURL, that would look like: curl -XPOST http://localhost:1123/signup --data '{"name": "YOUR_NAME", "days_signed_up_for": 3}'. You should now see a response indicating how many days you're signed up for.
To see that you really put a sign-up in the database entity, open sqlite3 in the command line, open the database again with .open website.db, and finally, run SELECT * FROM signups. You should now see a single item in the database.

(11) Make a GET endpoint that retrieves a piece of data from the database

Go code

First, add a new method to the signupsDB type for retrieving signups by name

// SQLite syntax more or less saying "get the "name" and
// "days_signed_up_for" fields of AT MOST one item in the
// signups table whose name matches the question-mark
// parameter"
const getSignupQuery = `SELECT name, days_signed_up_for FROM signups WHERE name=? LIMIT 1`

func (db *signupsDB) getByName(name string) (*signup, error) {
    // retrieve a single item from the "signups" database
    // table. We get back a *sql.Row containing our result, or
    // lack thereof if the item we want is not in the database
    // table.
    row := db.db.QueryRow(getSignupQuery, name)

    // We deserialize the Row to the data type we want using
    // Row.Scan. If no database entity had been retrieved,
    // then we instead get back sql.ErrNoRows.
    var s signup
    if err := row.Scan(&s.Name, &s.DaysSignedUpFor); err != nil {
        return nil, err
    }
    return &s, nil
}

Then, make a new endpoint that uses getByName to query for signups

func handleGetSignupFromDB(w http.ResponseWriter, r *http.Request) {
    name := mux.Vars(r)["name"]

    w.Header().Set("Content-Type", "application/json")
    signup, err := db.getByName(name)
    switch err {
    case nil:
        // if there's no error, we have a signup, so carry on
        // with sending it as our JSON response
    case sql.ErrNoRows:
        // if we got ErrNoRows, then return a 404
        w.WriteHeader(http.StatusNotFound)
        w.Write([]byte(`{"error": "sign-up not found"}`))
        return
    default:
        // for any other kind of error, return a 500
        w.WriteHeader(http.StatusInternalServerError)
        w.Write([]byte(`{"error": "unexpected error"}`))
        return
    }

    if err := json.NewEncoder(w).Encode(signup); err != nil {
        w.WriteHeader(http.StatusInternalServerError)
        w.Write([]byte(`{"error": "couldn't serialize to JSON"}`))
    }
}

Finally, add handleGetSignupFromDB to router

rt.HandleFunc("/signup/get/{name}", handleGetSignupFromDB)

Running the server

Compile and start the server again
Send a request to the http://localhost:1123/signup/get/YOUR_NAME. You should now see the JSON of your sign-up you did in the last step.
Send another request to the signup endpoint, this time with the name of someone that didn't sign up. You should now see the JSON of a sign-up not found error.

Introducing the #WebDevSampler challenge

Andy Haskell — Wed, 10 Aug 2022 02:29:03 +0000

There are a lot of programming languages you can use to code the server for your web app, but regardless of which one you use, there are core concepts you will always need to know how to do. Some of those are things like routing, security, database interactions, serialization to formats like JSON, and HTTP.

With all the different concepts to be thinking about, and all the different tools and frameworks you can choose from, learning web development can be understandably overwhelming to get going with. But one thing that I find helps when learning a new tool, is breaking down what I'm learning into bite-size tasks, especially when they build on each other.

So for trying out a new language's web development stack, see if I like it, and get feedback on implementation patterns, I am trying something called #WebDevSampler as a set of bite-sized excercises for starting web development in a new programming language. The idea of the challenge is:

#WebDevSampler assumes you know the fundamentals for the language, such as iteration, functions, data types, and compiling/running a program.
- The ninth exercise assumes are familiar with using an HTTP client like cURL, httpie, or Postman to send a JSON payload to an HTTP endpoint.
- The final two exercises, the database ones, do assume familiarity with talking to at least one kind of database. But I left it vague which database to use so you can use the one you like best. I am using SQLite in my own example.
Each exercise is intended to be the relatively simple so the code changes it entails can demonstrate the concept.
Each exercise builds on each other, so they are intended to be run in order.
For any exercise, what you use to solve the problem is up to you, which is why what you build in an exercise is intentionally vague. You can use just the standard library in the language, or you can use dependencies like libraries, microframeworks, and even big frameworks (but I personally wouldn't start in a new language with the big Rails-like framework for that language, unless you know you want to be using that framework on the job).
- In fact, you're encouraged to try tools out in your language and compare them to see which ones you like best, and to learn about which tools are commonly used on the job in your language's web developer community. And you're encouraged to try installing at least one dependency so you can see how package management works in the language.
Want to do other experimentation with your code that's not on the exercises? Then you should! Going off the beaten path is a great way to learn more stuff, and you do a lot of that in a web development job!

The exercises are:

(1) Get an HTTP server up and running, serving an endpoint that gives the HTTP response with a message like "hello world!".
- Concept demonstrated: starting an HTTP server and processing an HTTP request.
(2) Give that HTTP response as HTML, with Content-Type text/html
- Concept demonstrated: editing the HTTP response using response headers
(3) Adding another endpoint/route on your HTTP server, such as an /about.html page
- Concept demonstrated: serving more than one HTTP endpoint
(4) Serving an endpoint with an image or webpage in your file system
- Concept demonstrated: serving content from a file system
(5) Route to an endpoints using more complex route like /signup/my-name-is/:name, for example if I send a request to /signup/my-name-is/Andy I would get back "You're all signed up for the big convention Andy!"
- Concept demonstrated: Parameterized routing
(6) Write and run an automated test for your HTTP parameterized endpoint
- Concept demonstrated: Automated testing with an HTTP endpoint in one of your language's testing CLI tools.
(7) Escape HTML tags in your endpoint. For example, /signup/my-name-is/<i>Andy should be sanitized so you DON'T display your name in italics
- Concept demonstrated: Basic input sanitization
(8) Serialize an object/struct/class to some JSON and serve it on an endpoint with a Content-Type: application/json
- Concept demonstrated: JSON serialization, which is done a lot creating backend APIs
(9) Add a POST HTTP endpoint whose input is of Content-Type application/json, deserialize it to an object/struct/class, and then use some part of the object to produce some part of the HTTP response.
- Concept demonstrated: JSON deserialization
(10) Now have that POST endpoint save the content to some database (MongoDB, Postgres, Cassandra, any database you want)
- Concept demonstrated: Database input
(11) Now make a GET endpoint that retrieves a piece of data from the database
- Concept demonstrated: Database retrieval

If you want to see my answers in Go, which I've been coding in professionally for 7 years, you can check them out here.

Where to after the challenge?

If you worked through the examples, congratulations and I hope you learned something about how web development is done in your language!

Since this was a sampler, the exercises were intended to give just a taste of each of the web development concepts they talk about. So if you are newer to web development, a good next stop would be to search the concepts that the exercises cover and keep learning more about them, for example in the input sanitization exercise, as I alluded to in the code comments, in a production app I would be more likely to be generating HTML using a library that has user data sanitization built-in, and also have a more rigorous set of unit tests to cover possible security holes. While in the database examples, I would be building out the rest of the CRUD (Create, Read, Update, Delete) methods to talk to the database.

If you've already done web development in another language, the next stop I would recommend taking is to look at more of the ecosystem of the programming language you did this challenge in. Like frameworks, package management, language idioms, and popular libraries for solving problems in web development.

And regardless of experience level, I recommend checking out your programming language's community, which in particular is great for networking (I got my first job in Go through networking at Boston Go in 2015!), getting familiar with other people's code in the language, and if you're looking to do public speaking in a new programming language, a meetup in that language is a great opportunity.

Finally, I definitely encourage you to share your answers in your language on here, tweeting at me at @AndyHaskell2013, on GitHub, or anywhere else with the hashtag #WebDevSampler

#GopherDiggingRuby: Intro to blocks in Ruby

Andy Haskell — Sat, 22 Jan 2022 21:27:05 +0000

When you're coding in Ruby, one piece of syntax you'll see a lot of is blocks, with either the curly braces or do...end syntax. So in this tutorial, we will take a look at how we can use blocks as convenient feature of a Ruby developer's toolbelt, and how that compares to Go.

🐼 Looping over collections with Lola

In Go, the idiomatic way to loop over a slice is with the range keyword, like this:

var doggoTricks = []string{
    "roll over", "speak", "shake paws", "toodle-oo",
}

for _, trick := range doggoTricks {
    fmt.Printf("Lola! Can you %s?\n", trick)
    lola.DoTrick(trick)
}
fmt.Println("Good pupper! Have a biscuit! 🦴")

In the for loop's top line, we loop over the doggoTricks slice one item at a time, putting the current dog trick in the variable trick. Then, inside the block, we use the trick variable to tell my dog Lola to do that trick, and then she does the trick using the function lola.DoTrick. And because of the curly braces block, the varable trick is scoped to only exist inside the for loop.

Ruby does have loops of its own, but another cool, and in my opinion quite satisfying way of looping over a Ruby array is with the Array#each method. Doing the same loop in Ruby looks like this:

doggo_tricks = ['roll over', 'speak', 'shake paws', 'toodle-oo']

doggo_tricks.each do |trick|
  puts "Lola! Can you #{trick}?"
  lola.do_trick trick
end
puts "Good pupper! Have a biscuit! 🦴"

The part do |trick| ... end is the block, and inside the pair of pipe (these |) characters, you name the variable that's scoped to the block. Then, inside the block, you can use that variable, such as printing it with puts and passing it into lola.do_trick.

In addition to looping over arrays, there's also an each method for hashes that works similarly to looping over maps in Go. And each isn't the only method that takes in a block; you can also use blocks on methods like Array#sort to influence how an array is sorted, Array#map to create a new array by running the code in the block on each item in the current array, and Array#filter to return an array of only the items where the block's code would return true.

As an example, if we had code like

with_paws = doggo_tricks.filter { |trick| uses_paws trick }

then the with_paws array would only have tricks where uses_paws is true, which includes toodle-oo and shake paws.

If you read my last tutorial on building a dev.to fetcher in Ruby, by the way, a couple places where we used blocks in this way were:

with Array.map to convert an array of Ruby hashes to an array of Article objects
walking a Markdown document's nodes

By the way, toodle-oo is Lola's signature trick, and it's really cute!

🌺 Having an object only in the part of the code where you need it, as told by making a smoothie

Another great use of blocks in your code is when you want to declare a variable, use it, and then do any clean-up code afterwards, like if you're opening a file, reading it into some kind of data structure, and then closing it when you no longer need that File variable, for example. When a Ruby API has use cases following that pattern, blocks are a common way to do that pattern.

As a more fun example, when it's a hot day out, nothing cools off a sloth like a refreshing hibiscus and cecropia leaf smoothie, fresh from the blender. Without blocks, the Ruby code would look something like this:

blender = get_blender()
blender.add('ice cubes', 'hibiscus flowers', 'cecropia leaves')

blender.serve_drinks()

# now on to more Ruby code for the rest of a sloth's day!

The one problem with this code is, the blender variable is still in scope, and if this is in the middle of a long section of Ruby code, it's easy to forget to call clean_up(blender) and put_back(blender).

The Go approach to making sure that code gets called would be to either use defer like this:

blender := getBlender()
defer func() {
    cleanUp(blender)
    putBack(blender)
}

blender.Add("ice cubes", "hibiscus flowers", "cecropia leaves")
blender.ServeDrinks()

// now on to more Ruby code for the rest of a sloth's day!

The Go function in the defer statement runs at the end of the Go code block we're in, so no matter what branches of code we take, cleanUp(blender) and putBack() blender will be called.

For a Ruby approach with blocks, let's say that this get_blender function had clean_up(blender) and put_back(blender) built-in. Then, the Ruby code for serving smoothies for sloths would look like this:

get_blender do |blender|
  blender.add(
    'ice cubes', 'hibiscus flowers', 'cecropia leaves'
  )
  blender.serve_drinks
end

We put the code we want to run into the block, and use the variable blender inside the block to add the ingredients and then serve the smoothies. Then, behind the scenes, get_blender calls the cleanup code. The person using our blender API, and the people reviewing their code, don't need to pore over lines of code to make sure all the cleanup code is called, because that's built right in, saving time and bug fixes for your dev team!

In my last tutorial on building a dev.to image link fetcher in Ruby, by the way, a couple places where we used blocks in this way were:

Sending an HTTP request to dev.to, deserializing the response from JSON, and then no longer needing the response body to be in-scope
Generating a CSV file object, and then inside the block adding the image links as rows of the CSV

🍹 Making your own functions that use blocks

One final thing to look at for demystifying Ruby blocks, is how to make your own code that works with them. To do that, we use a keyword called yield. This keyword confused me when I was first learning Rails, but essentially you can use yield to do the pattern of:

Run any code that's before the yield keyword
yield 0 or more Ruby objects that can be passed into the block
Then, run any code past the yield keyword

Let's try that out by giving the get_blender function a definition:

def get_blender
  blender = take_blender_out_of_cabinet()
  blender.plug_in()

  yield blender
  clean_up blender
  put_away blender
end

We first run take_blender_out_of_cabinet() and blender.plug_in() to get the blender ready. Then, we run yield blender. At that point, the coder using our blender can run a block that has the blender passed in as a variable in the block's scope. We run that code, and then return to the body of the get_blender function, where we call clean_up blender and put_away blender to clean up after the sloths enjoy a nice tasty smoothie!

You don't need to necessarily just use a block once in a function, by the way. Remember how we used the Array filter and each methods with blocks that run on each item in an array? Let's say we had some prep work to do before putting the ingredients into the blender. Before blending the hibiscus flowers and cecropia leaves, let's wash them, which we can do by using yield inside a loop, like this:

class Blender
  def add(*ingredients)
    # do prep work for the smoothie here!
    for ingredient in ingredients
      yield ingredient
      add_ingredient_to_blender ingredient
    end

    self.now_make_the_smoothie!
  end
end

For each ingredient we pass into add, we yield the ingredient to the block passed in before putting it in the blender. Finally, with all that done, we now_make_the_smoothie!

So now, the code for adding our smoothie ingredients would look like this:

blender.add(
  'ice cubes', 'hibiscus flowers', 'cecropia leaves'
) do |ingredient|
  if need_to_wash? ingredient
    wash ingredient
  end
end

In the block we are using, we pass the ingredient into need_to_wash?, and then wash the ones where need_to_wash? returns true (ice cubes are already made of water to begin with so no need to wash them). We run the block for each ingredient one at a time, so with all our smoothie ingredients prepped and put in the blender, we finally call blender.now_make_the_smoothies! to get refreshing hibiscus-cecropia smoothies to get just the energy you need for a long slothful day, brought to you by blocks!

For more information about how yield and yield_self, I recommend looking at this blog post by RubyGuides.

#GopherDiggingRuby: Make a dev.to image link fetcher in Ruby

Andy Haskell — Tue, 18 Jan 2022 05:59:16 +0000

I write a lot of blog posts on dev.to and really like using Markdown for blogging. But one thing that would make the blogging process even more convenient, is if I had all the image links I've made on previous dev.to posts in one place for reusing images.

So in this tutorial, I will show how we can use Ruby packages to make a CSV file of every image link in your blog posts from the command line, using the dev.to/Forem API.

We will:

💻 Send an authenticated request to the dev.to API with the standard library net/http package and the Forem API
🐈 Deserialize JSON into objects of a custom class with the standard library json package
💎 Retrieve the image links using the commonmarker gem
💼 Serialize objects into CSV files with the standard library csv package

This tutorial assumes you're familiar with JSON, HTTP requests, and the basics of Ruby.

Contacting the dev.to API

The first thing you need in order to talk to a web API is an API client. An API client is some code that sends authenticated HTTP requests to the web API. We can get a client in one of two ways:

Search for a Ruby Gem of a client for the dev.to/Forem APIs; a lot of people have made code repositories for talking to websites' APIs so that other people can use them.
Make our own API client from scratch

Since we're only talking to one HTTP endpoint on dev.to's API in this tutorial, we'll go with the second option. So let's jump to dev.to's API documentation!

The endpoint we're talking to is the User's Articles endpoint, which lists all articles belonging to the user calling that endpoint as JSON. Looking at the request and response samples on the right, we will find that:

The request is a GET request to the endpoint /articles/me
The response is an array of JSON objects
- Each JSON object in the array contains many fields for all the data representing the article, namely title for the title of the article, and body_markdown for the Markdown of the entire text of the article
The sample cURL request contacting that endpoint contains the header api-key, which tells dev.to who you are and gives you access to your own account's data.

So we need a client class that can:

Send an HTTP request to the dev.to API's /articles/me endpoint, with an API key as authentication
Deserialize the JSON response to Ruby objects, giving us access to the fields we are interested in.

If you're following along, make a folder for your Ruby app and write this code to app.rb in that folder:

require 'net/http'
require 'json'

class DevToClient
  def initialize(api_key)
    @api_key = api_key
  end

  def get_my_articles
    # [TODO] Send HTTP request to /articles/me and deserialize
    # the JSON response
  end
end

We have a DevToClient class with two methods:

initialize as its constructor. In the constructor, we pass in our API key, and it gets stored in the instance variable @api_key
get_my_articles, which will send an HTTP request to dev.to's /articles/me endpoint that uses the @api_key and deserialize the response

Now for getting the HTTP response. Looking at the documentation for net/http, there is the method HTTP.get_response for sending a GET request to the URL passed in and getting back an HTTP response.

From the get_response method's documentation, in addition to a URL, we also are able to optionally pass in a hash of any request headers we want to pass in. So we can pass in an api-key header with this code:

  def get_my_articles
    Net::HTTP.get_response(
      URI('https://dev.to/api/articles/me'),
      { 'api-key': @api_key }
    )
  end

We send the request to dev.to's /api/articles/me endpoint with an api-key header containing the value of the DevToClient's @api_key instance variable.

To run this, you are going to need to get your own API key for the dev.to API. To do that, first, make a dev.to account if you don't have one already. Then, you can get your API key by following the Authentication instructions on the dev.to API docs.

⚠️WARNING!⚠️ For any web API you are working with, DO NOT share your API key or other forms of authentication with anyone; don't post it online or email it to your friends, and also don't commit it in your code! If someone else gets ahold of your API key, they will be able to impersonate you on that API and access your account data! If you suspect that someone has obtained one of your authentication keys or secrets, you should have that key/secret invalidated and then a fresh API key/secret created to protect your account.

Now, your save your API key to the environment variable DEVTO_API_KEY. Then, at the bottom of app.rb, add this code:

api_key = ENV['DEVTO_API_KEY']
puts DevToClient.new(api_key).get_my_articles

Run the code with ruby app.rb and you should see terminal output like this:

#<Net::HTTPOK:0x00007fc20a92f800>

We got back a response of class HTTPOK (which inherits from HTTPSuccess and in turn inherits from HTTPResponse). So now we have our response, so let's parse it to make Ruby objects for each article.

JSON parsing in Ruby

In addition to net/http, the Ruby standard library has a json package for serializing deserializing JSON, and inside that package there is the method JSON.parse. So if we did Ruby code like

sloth_json = <<EOF
{
    "sci_name":    "Bradypus",
    "common_name": "Three-toed sloth",
    "claw_count":  3
}
EOF

sloth = JSON.parse(sloth_json)
sci_name = sloth["sci_name"]
common_name = sloth["common_name"]
claw_count = sloth["claw_count"]
puts "The #{sci_name} (#{common_name}) has #{claw_count} claws"

and then ran ruby app.rb, we would get output like this:

The Bradypus (Three-toed sloth) has 3 claws

The object returned from JSON.parse is a Ruby hash, with its field names becoming the hash's keys.

Let's try JSON.parse to return a Ruby object from DevToClient#get_my_articles:

  def get_my_articles
    res = Net::HTTP.get_response(
      URI('https://dev.to/api/articles/me'),
      { 'api-key': @api_key }
    )

    if res.code.to_i > 299 || res.code.to_i < 200
      raise "got status code #{res.code}"
    end
    JSON.parse res.body
  end

Now, if we got a status code besides 2xx, we raise an error. Otherwise, we return the result of parsing the response body.

If you then ran code like

puts DevToClient.new(api_key).get_my_articles

you will see that the Ruby object that the response body deserialized to was an array of Ruby hashes. So we could do something like this:

DevToClient.new(api_key).get_my_articles.each do |article|
  md = article["body_markdown"]

  # now use a Markdown file to find every image link in
  # the article
end

But what if we wanted a DevToArticle class that handles digging for all the image links, and we wanted to deserialize our JSON to an array of DevToArticles instead of hashes?

Let's start by making a DevToArticle class:

class DevToArticle
  attr_accessor :id, :title, :body_markdown, :url

  def initialize
    # [TODO] Add deserialization logic here
  end

  def get_article_images
    # [TODO] Add Markdown parsing for the article's
    # @body_markdown
  end
end

Since Ruby doesn't directly know if that the JSON it's getting is supposed to be a DevToArticle, calling JSON.parse will return an array of Ruby hashes. So we will need just a bit of extra logic for converting those hashes to DevToArticles.

I wasn't sure how to do this at first; in Go, the main programming language I work with, I would be doing this using code like this:

type DevToArticle struct {
    ID           int    `json:"id"`
    Title        string `json:"title"`
    BodyMarkdown string `json:"body_markdown"`
    URL          string `json:"url"`
}

func (d *DevToClient) GetMyArticles() ([]DevToArticle, error) {
    // get the HTTP response for the "user's articles" API
    // endpoint here

    var articles []DevToArticle
    if err := json.NewDecoder(res).Decode(&articles); err != nil {
        return nil, err
    }
    return articles, nil
}

I searched for how to deserialize to a custom class rather than a hash, and after asking about that on Twitter, Jamie Gaskins told me that there isn't really a standardized way in Ruby to deserialize to a class, but you are able to give your Ruby class an initialize method that takes in a hash. So based on that advice, in our DevToArticle#initialize class, the deserialization logic would look like this:

  def initialize(attributes)
    @id = attributes['id']
    @title = attributes['title']
    @body_markdown = attributes['body_markdown']
    @url = attributes['url']
  end

For each field we want an instance variable for, we just pull it out of the attributes hash passed in.

Note, by the way, that this also gives us control of the casing scheme for the deserialized objects. In Ruby, the standardized casing for instance variables is snake_case, and that's the casing the Forem API uses, but what if Forem was a camelCase API instead? @body_markdown still is able to be snake_case even if bodyMarkdown in the hash is camelCase:

    @body_markdown = attributes['bodyMarkdown']

Now, to have DevToClient#get_my_articles return an array of DevToArticles instead of an array of hashes, we can do this:

    articles = JSON.parse(res.body)
    articles.map { |article| DevToArticle.new article }

By passing that block into articles.map, we get back an array of DevToArticles created from each hash in the articles array, so now get_my_articles returns the type we want: an array of DevToArticles. Now let's jump into the Markdown of those articles all their image links!

Markdown parsing with commonmarker

Unlike HTTP and JSON, the standard library in Ruby doesn't have a Markdown package, so we can either write our own Markdown parser, or use a Markdown-parsing Ruby Gem.

And it turns out that there's a popular Ruby Gem that lets us parse a Markdown file and then walk over its nodes (nodes as in text, links, images, etc): CommonMarker! To get it, first run bundle init to create a Gemfile, then in the Gemfile, add the line

gem "commonmarker"

Then run bundle install. If CommonMarker it successfully installs, you should be able to use it in your Ruby code.

To start, add require 'commonmarker' to the top of app.rb, then in DevToArticle#get_article_images, add this code:

  def get_article_images
    doc = CommonMarker.render_doc(@body_markdown, :DEFAULT)
    puts doc
  end

If you run that function in app.rb, you will get output for an article like:

#<CommonMarker::Node:0x00007fca8718f228>

indicating that we were able to parse the Markdown in @body_markdown, converting it to a CommonMarker::Node object.

Following this example in the CommonMarker documentation, we can walk over all the nodes in the document with code like this:

  def get_article_images
    doc = CommonMarker.render_doc(@body_markdown, :DEFAULT)
    doc.walk do |node|
      puts node.type
    end
  end

Now in the do block, we are looking at each Node and seeing what type of node it is. So if you run this code, you might see output like this:

text
code
text
paragraph
image
text
text
paragraph

We're only interested in image nodes, so we'll add an if statement to check the node's type, which according to the documentation, is the Ruby symbol :image according to the new(p1) docs.

    doc.walk do |node|
      if node.type == :image
        # [TODO] retrieve the node's content
      end
    end

Now we're only processing image links. And a Markdown image link has two parts: descriptive alt text, which screen reader software reads when viewing images, and the URL of the image. So we need to find ways to get both of those.

Looking at the CommonMarker documentation, the Node method for getting the alt text is to_plaintext, and the Node method for getting the URL of the image is url. So now, we can return the parts to the image link:

  def get_article_images
    doc = CommonMarker.render_doc(@body_markdown, :DEFAULT)
    image_links = []
    doc.walk do |node|
      if node.type == :image
        image_links.push [
          node.to_plaintext.delete_suffix("\n"), node.url
        ]
      end
    end

    image_links
  end

So now, we have all the data we'll need for serializing to a CSV file!

Serializing your image links to a CSV file

The Ruby standard library also comes with a csv package for parsing CSV files, or generating them from arrays of data. Each row will be one image link, including:

The alt text of the image link
The URL of the image
The ID of the article that the image link came from
The title of the article that the image link came from
The URL of the article that the image link came from

So we will want CSV header text like:

Alt Text,Image URL,Article ID,Article Title,Article URL

And for each row in the CSV, we will want an DevToImageLink Ruby class to represent all the data in that row

class DevToImageLink
  def initialize(article, image_alt, image_url)
    @article = article
    @image_alt = image_alt
    @image_url = image_url
  end

  def to_csv_row
    [@image_alt, @image_url, @article.id, @article.title, @article.url]
  end
end

In the initialize method we pass in the DevToArticle for the image link, and the alt text and URL of the image, to become instance variables. And in the to_csv_row method, all of these fields are put into a Ruby array.

Heading back to the DevToArticle class, now that we have the DevToImageLink class defined, let's have DevToArticle#get_article_images return an array of DevToImageLinks, rather than an array of arrays:

      if node.type == :image
-       image_links.push [node.to_plaintext, node.url]
+       image_alt = node.to_plaintext
+       image_url = node.url
+       image_links.push DevToImageLink.new(self, image_alt, image_url)
      end

Now that that's all set, let's add a top-level get_image_links_csv function that will convert our article to a CSV.

def get_image_links_csv(api_key)
  CSV.generate do |csv|
    csv << [
      'Alt Text','Image URL','Article ID','Article Title','Article URL'
    ]

    DevToClient.new(api_key).get_my_articles.each do |article|
      article.get_article_images.each do |image_link|
        csv << image_link.to_csv_row
      end
    end
  end
end

The function CSV.generate takes in a block and returns the CSV string generated in that block.

In the first line inside the block, we pass in our CSV headers with the CSV's << method, so they will serve as the first line of the CSV.

Now, we loop over the image links in each of the articles returned by DevToClient#get_my_articles. For each image link, we call the DevToImageLink#to_csv_row method, and then load the returned array into the CSV.

Finally, the return value of CSV#generate is a string in CSV format. So now, we can use that code like this:

puts get_image_links_csv(api_key)

Using three standard library packages and a gem, we were able to make a convenient script for getting all our dev.to image links and converting them to a CSV. In my next Ruby tutorial, I will be looking at using a gem for giving this script a better user experience so it's easier to search the CSV for the image you want.

Convert images to mosaics in p5.js

Andy Haskell — Sat, 01 Jan 2022 22:22:54 +0000

p5.js is a fun JavaScript library for drawing on an HTML5 canvas, and it has some of the clearest tutorials I have seen. It gives you functionality for things like image manipulation, drawing lines and shapes, displaying images, working with trigonometry, and more. And it is especially popular for generative art, such as fractals.

In this tutorial, I will show you how to use p5.js to convert an image like this:

to a mosaic of dots like this:

This tutorial assumes a working knowledge of JavaScript and familiarity with pre-algebra, but prior knowledge of p5.js isn't strictly necessary. You can follow along on this by creating an account on the p5.js online editor and logging in. The finished product can be found here.

📝 Making a first canvas

As a basic p5.js program, let's start by making a canvas and drawing a single small dot there. We would do that by taking this code to the p5.js editor:

function setup() {
  createCanvas(300, 200);
}

function draw() {
  ellipse(50, 60, 15, 15);
}

We are starting with basic implementations two of the major functions in a p5.js program: setup and draw.

The setup function runs at the beginnng of a p5.js program, and what we're doing in it is calling createCanvas, a built-in function from p5.js, to create a small HTML5 <canvas> element of width 300 and height 200.

The draw function runs repeatedly in the JavaScript event loop, and what we're doing is calling ellipse to put a circle on the canvas, with a diameter of 15 pixels and its center at point (50, 60) of that canvas. Remember at school plotting points on Cartesian coordinate grids in math class? That is the same concept here with drawing on a canvas. In fact, a lot of concepts from math class can be used as tools to make cool art!

Now that we've got our setup and draw functions, press play on the p5.js editor, and you should see something like this:

One key difference between the Cartesian grids in math class, and the ones in an HTML5 canvas, though, is that as you can see, point (50, 60) is at the top-left of the canvas, not the bottom-left. Unlike in the graphs from math class, the y-axis on an HTML5 canvas goes from top to bottom, not bottom to top. The x-axis, though, still goes left to right.

By the way, since we're only drawing our picture once rather than repeatedly (like if we were making an animated p5.js sketch), it's kind of pointless to call draw repeatedly. So let's make it so we're only calling draw once.

  function setup() {
    createCanvas(300, 200);
+   noLoop();
  }

By adding a call to noLoop, now after the first time we call draw, we don't call draw again unless our code calls redraw.

Before we move on to loading an image, one other thing worth noting, circles/ellipses are not the only shape you can draw in p5. You can find code to draw other shapes, like lines, curves, rectangles, and more, in the links at this reference.

📷 Loading an image

We've got our canvas made, but now we need a way of loading the image we're editing.

First, in the p5 editor, left of the sketch.js filename, click the right arrow to pop our the "sketch files" panel, click the down triangle on the line that says "sketch files", select "upload file" in the dropdown, and then upload your image.

Now, to use the image, add the following code to the p5.js editor, adding a preload function and replacing the setup function:

let img;

function preload() { img = loadImage('./beach.jpg'); }

function setup() {
  createCanvas(img.width, img.height);
  noLoop();
}

The preload function runs before setup to load any assets needed for our p5.js program. What we're doing in our preload function is calling p5.js's loadImage function to load an image, represented in JavaScript as a p5.Image object, that we can manipulate. We store that Image in the img global variable. Note that if you're using an image besides beach.jpg, you'll want to change the name of the image you're loading in loadImage.

Now, in setup, we call createCanvas like before, but now we use the Image object to load the image. We then retrieve the image's width and height so the canvas we make is now the same size as the image.

Now that we've got the image's width and height, and a canvas made in that size, we're going to switch over to drawing the dots on our mosaic.

🐆 Plotting the dots

Circling back to our draw function, let's replace that function's entire code with this:

function draw() { drawMosaic(5) }

function drawMosaic(dotRadius) {
  // [TODO] Add code to put the dots on the mosaic!
}

Just like how in programming languages like Go, it's a good idea to have the main relatively simple, I like having my draw function be just a one-liner that calls the function that does the bulk of the action. We're going to have drawMosaic be the central function of this program; it takes in the radius we want each dot to be, and it will be in charge of drawing all our dots.

We want dots all over the picture, so let's break up the image into columns; each column will be about 1.5 times the width of a dot (3 times the radius), and will be filled top to bottom with dots. So we'll need to know:

How many columns the image will have
With that knowledge, how to draw a column.

Let's start by just displaying a vertical line for each column. We'll get rid of the line later, but for now this is helpful as scaffolding, so if something is off about how we render the dots, such as what size they are, or where the dots are drawn, we can figure out what's being drawn in a given column relative to that column's lines.

So let's add these functions:

const columnWidth = (dotRadius) => dotRadius * 3;

const numberOfColumns = (dotRadius) =>
  Math.ceil(width / columnWidth(dotRadius));

function drawColumnDots(dotRadius, offsetX) {
  // [TODO] Replace the line with a column of dots
  line(offsetX, 0, offsetX, height);
}

function drawMosaic(dotRadius) {
  for (let i = 0; i < numberOfColumns(dotRadius); i++) {
    offsetX = i * columnWidth(dotRadius);
    drawColumnDots(dotRadius, offsetX);
  }
}

Here's our functions so far:

columnWidth is a helper function to get the width of a column. We have a column be triple the radius of a dot, so that we give each dot a bit of wiggle room as to where it will be drawn.
numberOfColumns tells us how many columns of dots we can fit in the picture. Which is the width of the image divided by the width of a column.
drawColumnDots will be in charge of adding all the dots to a given column, starting at the x-coordinate offsetX we pass in and ending at offsetX + dotRadius. For now, as scaffolding, we will just draw a straight vertical line at the left edge of the column.
drawMosaic draws every column; we loop over the number of columns we have, and for each one we create a column that starts at the x-coordinate i times the width of a column. For example, if we have a column width of 15, then the sixth column of dots (zero indexed, so i = 5) of the mosaic starts at an offsetX of 75 pixels.

Press play on the p5.js editor, and you should see something like this:

But we didn't come here to draw some vertical lines, we came here to draw some dots, so let's do that!

function drawColumnDots(dotRadius, offsetX) {
  // [TODO] Replace the line with a column of dots
  line(offsetX, 0, offsetX, height);

  let dotDiameter = 2 * dotRadius;
  let dotHeightWithPadding = dotDiameter + 2;
  let numDotsInColumn = Math.floor(height / dotHeightWithPadding);

  for (let i = 0; i < numDotsInColumn; i++) {
    let centerX = Math.floor(random(
      offsetX + dotRadius,
      offsetX + columnWidth(dotRadius) - dotRadius,
    ))

    let centerY = i * dotHeightWithPadding + dotRadius;

    ellipse(centerX, centerY, dotDiameter, dotDiameter);
  }
}

Here's what happens:

First, we declare variables for the diameter of a dot, and the height of each dot, with two pixels of padding so the dots aren't touching each other. We then divide the height of the image by dotHeightWithPadding to get the number of dots in the column.
Then, in the for loop, we will draw all the dots, from the top of the column to the bottom. First, we calculate the coordinates of the pixel at the center of the dot.
- For the x-coordinate, the leftmost position a dot can be is dotRadius pixels to the right of the start of the column. And the rightmost column is dotRadius pixels to the left of the end of the column. So if a column is 15 pixels wide with a 5-pixel dot radius, we would randomly select an x-coordinate between 5 and 10 pixels to the right of the start of a column.
- For the y-coordinate, each dot is dotHeightWithPadding pixels lower than the dot above it. We place the top dot's center at dotRadius pixels below the top of the pixel, so that the top dots don't get cut off.

Looks good, but we could use some randomness vertically too to so the dots aren't necessarily at the same height as the ones to the left and right of each other.

+ let topY = Math.floor(random(10));

  for (let i = 0; i < numDotsInColumn; i++) {
    let centerX = Math.floor(random(
      offsetX + dotRadius,
      offsetX + columnWidth(dotRadius) - dotRadius,
    ))

-   let centerY = i * dotHeightWithPadding + dotRadius;
+   let centerY = topY + i * dotHeightWithPadding + dotRadius;

    ellipse(centerX, centerY, dotDiameter, dotDiameter);
  }

Looks good! Before we go on to fill in the colors of the columns, remove the call to line, since we no longer need that piece of scaffolding.

🎨 Giving the dots their colors

The last step of drawing our mosaic is to color the dots. Each dot will be the same color as the color of the pixel at the center of the dot. Here's how we would do that:

  let dotColor = img.get(centerX, centerY);
  noStroke()
  fill(dotColor);

  ellipse(centerX, centerY, dotDiameter, dotDiameter);

Here's what happens:

First, we use Image.get to retrieve the color of the pixel at the coordinates (centerX, centerY). This is represented as an array of 4 numbers: red, green, blue, and alpha-transparency (how see-through a pixel is).
We call noStroke to remove the outline on the dots, and we call fill to set the color of a dot.
Finally, calling ellipse draws the dot in the color we selected.

Press play on the p5.js editor, and now the canvas will look like this:

Cool! One other thing I'd like to add though. This picture has a lot of light-colored pixels, so the dots would stand out better on a dark-colored background. So let's refactor drawMosaic so that you can pick the color of the background.

function draw() { drawMosaic(10, color(30, 30, 30)); }

function drawMosaic(dotRadius, backgroundColor) {
  background(backgroundColor);

  // ... rest of the code in the function ...
}

We add a new parameter backgroundColor to our drawMosaic function, and we pass that into background to draw a background. In draw, I picked the color 30, 30, 30; since red/green/blue go from 0 to 255, this gives us a charcoal-black background color. I also made the dot radius 10 pixels instead of 5 to make the picture feel more abstract. Run the play button on the sketch, and now the mosaic looks like this!

We've made a cool piece of artwork with just 46 lines of code, but we've only scratched the surface of the kinds of art you can do with p5.js. If you had fun with this, you should check out the docs for more of p5's code, other people's sketches and YouTube videos for ideas on how you can work with p5 concepts, and check out your old notes from math class to see what other kinds of math, like trigonometry, can be used to make cool artwork!

DEV Community: Andy Haskell

Conferencing tips as an autistic + ADHD conference-goer

Requesting and finding accommodations

A bag of tips on packing for the event

Prioritizing events to go to

Staying regulated and doing self-care at the event

Decide for yourself how much you feel willing/safe to "be yourself" at a conference

How AuDHD traits have helped me get good at devrel

Special Interests

ADHD novelty-seeking

Attention to detail

Accommodations still matter

Neurodiversity strengthens devrel!

Write your tech talk slides rapidly with Marp

Installing Marp

Writing our first title slide

Adding an image

Adding an "about me" slide

Code snippets and speaker notes

Using CSS in your slides

Using Testify Mock in web clients

📚 Setting up a fake API to test against

🥸 Basic test with mock

Wrapping our client in an interface

Writing a mock implementation of our client

Using our client in a test

⛔️ Handling error cases

Testing that our code handles internal server errors correctly

Testing the error case where the API doesn't have the sloth fact we want

📖 Pagination with MatchedBy, Once, and AssertNumberOfCalls

🧰 Testify Mock is just one tool for testing your web apps

Mocks in Go tests with Testify Mock

🎰 Getting some nondeterministic code and the Testify Mock package

✨ Using Testify Mock

1. Take the nondeterministic function calls and wrap them in an interface

2. Write an implementation of the interface that uses Testify Mock

3. In the tests, use the mock implementation and feed in results the function returns.

🐛 Finding and fixing a bug using Testify Mock

Processing user input in Bubble Tea with a menu component

📝 Defining our data

🧋 Implementing the Model interface

✅ Handling the enter key and seeing what the tea.Cmd type actually does

Intro to Bubble Tea in Go

🚧 Writing our first basic app

🧋 Model is the main interface of Bubble Tea

#WebDevSampler challenge - My answers in Go

(1) Get an HTTP server up and running, serving an endpoint that gives the HTTP response with a message like "hello world!".

Go code

Starting the program

(2) Give that HTTP response as HTML, with Content-Type text/html

Go code

Starting the program

(3) Add another endpoint/route on your HTTP server, such as an /about.html page

Go code

Starting the program

(4) Serving an endpoint with an image or webpage in your file system

Preliminary steps

Go code

Starting the program

(5) Route to an endpoints using more complex route like /signup/my-name-is/:name

Preliminary steps

Go code

Starting the program

(6) Write an automated test for your HTTP parameterized endpoint

Preliminary steps

Go code (in app_test.go)

Running the test

(7) Escape HTML tags in your endpoint.

Go code (main.go)

Go test code (main_test.go)

Running the test

Running the server

(8) Serialize an object/struct/class to some JSON and serve it on an endpoint with a Content-Type: application/json

Go code (near top of main.go)

Running the server

(9) Add a POST HTTP endpoint whose input is of Content-Type application/json, deserialize it to an object/struct/class, and then use some part of the object to produce some part of the HTTP response.

Go code (near top of main.go)

Running the server

(10) Save the input of your POST request to a database

Preliminary steps to using my implementation

(2) Give that HTTP response as HTML, with Content-Type `text/html`

(3) Add another endpoint/route on your HTTP server, such as an `/about.html` page

(8) Serialize an object/struct/class to some JSON and serve it on an endpoint with a `Content-Type: application/json`

(9) Add a POST HTTP endpoint whose input is of Content-Type `application/json`, deserialize it to an object/struct/class, and then use some part of the object to produce some part of the HTTP response.