Frontend Debugging Checklist

Posted by Dustin Boston on in .

This guide shows you how to find and fix bugs.

  1. First, you prepare.
  2. Next, you find the cause.
  3. Then you fix the bug.
  4. Finally, you learn from it.

I. Prepare and Prevent

The best bug is a bug that doesn’t happen. Good work stops bugs before they start. It makes them easy to fix.

  • Write clean code. Use good names for things. Break the code into small parts. Add clear comments. Don’t use hard-coded values. Write in one style. The code will be easier to read. Bugs will be easier to find.
  • Use a linter. Tools like ESLint or Prettier check your code. They find errors and style problems. They do this before the code runs. If you haven’t run your linter, do it now.
  • Write tests. Write tests for functions and components. Use tools like Jest or React Testing Library. Run tests often so you can find bugs early. It will keep old bugs from coming back.
  • Use Git. Commit your code frequently. Use branches for new work. If you break something, you can go back.
  • Update your tools. Keep your libraries up to date. You’ll get bug fixes. It’s more secure. And it ensures that everything works together.
  • Keep good notes. Use comments to explain complex code. You’ll thank yourself later.

II. Find and Repeat the Bug

You can’t fix what you can’t find. First, you need to make the bug happen again. And again.

  • Know what should happen. Know what the code should do. Know what it does instead. That gives you a goal.
  • Make the bug happen every time. Find the steps that cause the bug. Find the input that breaks it. Short and simple steps are best. They make the work faster.
  • Isolate the problem.
    • Try a Private Window. Open the app in private mode. It will turn off extensions and use fresh data. These can cause bugs.
    • Clear the cache. If the bug is still there, clear the cache. Clear the cookies. Inspect local storage. Then do a hard refresh to load the newest code.
    • Test on Other Machines. The bug may be in one place. Test it in a new place. Test it on other browsers and machines.
    • Record the steps. Some bugs are hard to reproduce. Use a tool to record your steps.

III. Find the Cause

You have the bug. Now you hunt for the cause. You can hunt in layers using a system. We’ll use the OSI 7 Layer Model.
First, start with what the user sees. Then you work down to the machine level. Doing this prevents guess work.

Layer 7: Your Code

Layer 7 is your application. React. State. The code you wrote.

  • Use the dev tools. Use React dev tools. Look at your components. Look at their props. Look at their state. See what is wrong. If you use Redux, use its tools. See how the state changes.
  • Isolate the code. Use a tool like Storybook. Or make a new page. Run the component alone to rule out other problems. Make a small test case. Use fake data. Don’t depend on the backend.
  • Use breakpoints. You can set breakpoints that only stop when something is true. In the browser, you can make the code stop when an error occurs. Put debugger; statements in the code. Then look at the variables. Examine the call stack.
  • Use the Console. Use console.log() for information. Use console.error() for errors. Use console.warn() for warnings. Use console.table() to see objects and arrays. Use console.trace() to see the functions that came before. Use console.group() to keep logs together.

Layer 6: The Screen (DOM & CSS)

Layer 6 is what the user sees. It’s the styles and HTML.

  • Check the HTML. Use the Elements tab in your browser. Look for missing parts. Look for wrong tags. You can set a breakpoint to stop the code when the HTML changes.
  • Fix the styles. Use the “Computed” tab. Look at the final CSS. See what rules are in use. You can turn styles on and off to see what works.
  • Fix Layers. Z-index can cause bugs. Use the Layers panel to see how things stack.

Layer 5: The Browser’s Memory

Layer 5 is about data that the browser saves. Bugs here mean the app does not remember things.

  • Check Storage. Use the Application tab. Look at Local Storage. Look at Session Storage. Look at Cookies. You can change or clear them. Make sure the data isn’t corrupted.
  • Check the URL. The URL is a form of state. Check the params. Look for weird characters. Verify the protocol. Do you need a port?
  • Subdomains. Storage and cookies might apply to a specific URL. Check the Application tab to see the domain.

Layer 4: The Network

Layer 4 is how your code talks to the server. Bugs here are common.

  • Watch the Network. Open the Network tab. Look for red requests. Red means they failed. Check the status codes. A 4xx code is a client error. A 5xx code is a server error. Look for CORS errors.
  • Check the data. Look at what you send. Look at what you get back. Is the server getting what it needs? Is the frontend getting what it expects?
  • Fake Bad Conditions. Slow down the network. Go offline. Edit a request and send it again. You don’t have to change any code.

Layer 3: The Server

Layer 3 is about your Node.js code, or the backend for frontend (BFF).

  • Check the logs. The first step is to look at the logs. Look for errors and stack traces.
  • Debug the server. Run Node.js with the -- inspect flag. Use Chrome or VS Code to connect. You can set breakpoints in your server code.
  • Check environment variables. Make sure the server has the correct variables.
  • Check your tools. If the server does not start, it may be your tools. Delete node\_modules. Delete package-lock.json. Then run npm install to get a clean start. If you’re desperate, run git clean \-dfx. It will delete all untracked files.

Layer 2: The Build

Layer 2 is about how your code gets bundled.

  • Check for source maps. Your build should have source maps. Without them, you can’t debug production code. It’s almost impossible to untangle minified code.
  • Check the Build Log. Look for errors from your bundler. Webpack or Vite will tell you if something is wrong.

Layer 1: The Machine

The final layer is about your computer.

  • Use Git. If the code worked before, a change broke it. Use git bisect to find the bad commit.
  • Check your machine. Do you have two servers running? Are you on a VPN? Try reconnecting if you are.

IV. The Fix

Congrats! You found the bug. But the job isn’t done yet.

  • Change one thing. Make one change. Then test. Don’t make many changes at a time, or you won’t know what works.
  • Test the fix. Run your tests. Then write a new test for the bug. If it comes back, the test will catch it.
  • Test in other browsers. Make sure your fix works everywhere. Check Chrome, Edge, Safari, and Firefox.
  • Check for new bugs. A fix can break other things. Check the code around your fix. Check files that share your code. Make sure everything is still good.
  • Be sure. Bugs don’t fix themselves. If you don’t know how you fixed it, you haven’t fixed it. It will come back to haunt you.

V. Learn

Learn from the bug.

  • Write it down. Keep a log. Write down the problem. Write down the cause. Write down the fix. It will help you later.
  • Think about it. How did the bug happen? Could good code have stopped it? Could a new rule have prevented it? Could a better test have caught it?
  • Self-Reflection. What actions could you have taken instead?

VI. If You Are Stuck

You’ve tried everything. Now it’s time for some new eyeballs.

  • Take a break. When you stare at code for too long, you see nothing. Walk away. Eat a snack. Take a nap. The answer will come.
  • Talk to yourself. Explain the problem. Say it out loud. Step by step. You will hear the mistake in your own words. Also known as Rubber Ducking.
  • Ask for help. Talk to a friend. A fresh look is a good thing. But first, you must make a good report.

VII. A Good Bug Report

A good bug report gets you help.

  1. Title: Write a short, clear title.
    • Bad: “The submit button is broken.”
    • Good: “The submit button on the checkout page does not work with the promo code.”
  2. Environment: List the tools and machines.
    • URL, Browser, OS, Node.js version.
  3. Steps to repeat the bug. A clear list. Number the steps. Be exact.
  4. What should happen? Say what you expect.
  5. What actually happens? Say what went wrong. Take a screenshot. Give the error message.
  6. What have you tried? Show your work. It saves time. Use the layers from this guide.
    • “I cleared the cache and used a private window.” (Layer 5)
    • “The network call to /api/promo fails with a 400 error.” (Layer 4)
    • “I put a breakpoint in the handleSubmit function.” (Layer 7)

Code. Link to the code on GitHub. Others will be more willing to help if they don’t have to look it up.