Here's How I Solved a Weird Bug Using Tried and True Debugging Strategies

Remember the last time you encountered a UI-related bug that made you scratch your head for several hours? Maybe the problem occurs randomly, or occurs in a specific situation (device, operating system, browser, user operation), or is just hidden in one of the many front-end technologies in the project?

I have recently experienced the complexity of UI bugs again. I recently fixed an interesting bug that affected some SVGs in Safari browser without any obvious pattern or reason. I've searched for any similar questions, hoping to find some clues, but no useful results were found. Despite the obstacles, I managed to fix it.

I analyze the problem by using some useful debugging strategies that I will also cover in this article. After submitting the fix, I remembered a tweet posted by Chris earlier.

Write down the article you wished to find when searching for Google.

— Chris Coyier (@chriscoyier) October 30, 2017

…We are here.

Problem description

I found the following bug in an ongoing project. This is on a website that is online.

I created a CodePen example to demonstrate this problem so that you can check it yourself. If we open the example in Safari, the button may look as expected when loading. However, if we click the first two larger buttons, the problem will appear.

Whenever a browser draw event occurs , the SVG rendering in the larger button is incorrect . It's just truncated. It may happen randomly when loading. It may even happen when the screen is resized. No matter what the situation is, it will happen!

Here is my solution to this problem.

First, let's consider the environment

It is always a good idea to review the details of the project to understand the environment and the conditions for bugs.

• This particular project uses React (but this post doesn't require it).
• SVG is imported as a React component and is inlined into HTML via webpack.
• SVG is exported from design tools and has no syntax errors.
• SVG applies some CSS from stylesheets.
• The affected SVG is located in an HTML<div> Inside the element.<li> The problem only appears in Safari (noted on version 13).</li> <h3 id="In-depth-question"> In-depth question</h3> <p> Let's take a look at this question and see if we can make some assumptions about what is going on. Bugs like this can become complicated and we won't know immediately what's going on. We don't have to be 100% correct on the first attempt, because we will go step by step, forming hypotheses we can test to narrow down possible causes.</p> <h3 id="Form-assumptions"> Form assumptions</h3> <p> At first, this looks like a CSS issue. Some styles may be applied in hover events, breaking the layout or overflow properties of the SVG graphics. It also looks like the problem occurs randomly whenever Safari renders a page (drawing events when resizing the screen, hovering, clicking, etc).</p> <p> Let's start with the simple and most obvious path and assume CSS is the source of the problem. We can consider the possibility of a bug in Safari browser that causes SVG rendering to be incorrect when certain styles are applied to SVG elements (such as flex layout).</p> <p> By doing so, we <strong>form a hypothesis</strong> . Our next step is to set up a test that either confirms or refutes the hypothesis. Each test result produces new facts about the bug and helps to form further assumptions.</p> <h3 id="Simplify-the-problem"> Simplify the problem</h3> <p> We will use a debugging strategy called <strong>problem simplification</strong> to try to pinpoint problems. Cornell's CS lecture described this strategy as "a way to gradually eliminate parts of the code that is not related to bugs."</p> <p> By assuming that the problem lies in CSS, we can finally pinpoint the problem or eliminate CSS from the equation, thereby reducing the number of possible causes and the complexity of the problem.</p> <p> Let's try to confirm our assumptions. If we temporarily exclude all non-browser stylesheets, the problem should not occur. I do this in my source code by commenting out the following line of code from the project.</p> <pre class="brush:php;toolbar:false"> &lt;code&gt;import 'css/app.css';&lt;/code&gt;</pre> <p> I created a handy CodePen example to demonstrate these elements that do not contain CSS. In React, we are importing SVG graphics as components and they are inlined into HTML using webpack.</p> <p> If we open this pen in Safari and click the button, we still have this problem. It still happens when the page loads, but on CodePen we have to force it by clicking the button. We can conclude that CSS is not the culprit, but we can also see that only two of the five buttons face problems in this case. Let's remember this and move on to the next assumption.</p> <h3 id="Isolation-issues"> Isolation issues</h3> <p> Our next assumption states that Safari is in HTML<code><div> There is a bug when rendering SVG inside the element. Since the problem occurs on the first two buttons, we will <strong>isolate the first button</strong> and see what happens.<p> Sarah Drasner explains the importance of isolation, and if you want to learn more about debugging tools and other methods, I highly recommend reading her article.</p> <blockquote><p> Isolation is probably the strongest core principle in all debugging. Our code base can be huge, with different libraries, frameworks, and may contain many contributors, even people who are no longer involved in the project. Quarantine issues helps us slowly remove unnecessary parts from the issues so that we can focus on the solution alone.</p></blockquote> <p> It is also often referred to as a "simplified test case."</p> <p> I moved this button to a separate empty test route (blank page). I created the following CodePen to demonstrate the status. Even if we have concluded that CSS is not the cause of the problem, we should also exclude the bug before finding out the real cause of the bug to simplify the problem as much as possible.</p> <p> If we open this pen in Safari, we can see that we <strong>can't reproduce the problem anymore</strong> and <strong>the SVG graph displays as expected after clicking the button</strong> . <strong>We should not consider this change as an acceptable bug fix</strong> , but it provides a good starting point for creating minimal reproducible examples.</p> <h3 id="Minimal-reproducible-example"> Minimal reproducible example</h3> <p> The main difference between the first two examples is button combination. After trying all possible combinations, we can conclude that this problem only occurs when a drawing event occurs for a larger SVG graph next to a smaller SVG graph on the same page.</p> <p> We created a <strong>minimal reproducible example</strong> that allows us to reproduce bugs without any unnecessary elements. Using the smallest reproducible example, we can study the problem in more detail and pinpoint exactly the part of the code that is causing the problem.</p> <p> I created the following CodePen to demonstrate the smallest reproducible example.</p> <p> If we open this demo in Safari and click the button, we can see that the problem is happening and form the assumption that the two SVGs are somehow conflicting with each other. If we overlay the second SVG figure on the first figure, we can see that the size of the cropped circle on the first SVG figure matches the exact size of the smaller SVG figure.</p> <h3 id="Divide-and-treat"> Divide and treat</h3> <p> We narrowed the problem down to a combination of two SVG graphics. Now we will narrow down the problem to the specific SVG code that causes the problem. If we only have a basic understanding of SVG code and want to pinpoint the problem, we can use <strong>a binary tree search</strong> strategy and adopt a divide-and-conquer approach. Cornell University’s CS lecture describes this approach:</p> <blockquote><p> For example, starting with a large piece of code, place a checkpoint in the middle of the code. If the error does not occur at that point, it means that the error occurs in the second half; otherwise, it is in the first half.</p></blockquote> <p> In SVG we can try to remove from the first SVG<code><filter></filter> (as well as<defs></defs> because it is empty anyway). Let's check first<filter></filter> The role of This article by Sara Soueidan explains it best.

  Like linear gradients, masks, patterns and other graphic effects in SVG, the filter has a dedicated element that is conveniently named:<filter></filter> element.

  <filter></filter> An element is never rendered directly; its only purpose is to reference it using the filter attribute in SVG or url() function in CSS.

  In our SVG,<filter></filter> A slight inner shadow is applied to the bottom of the SVG graphics. After we remove it from the first SVG graph, we expect the inner shadow to disappear. If the problem persists, we can conclude that there is a problem with the rest of the SVG tag. If we go from<g filter="url(#filter0_ii)"></g> delete the remaining ids in , and the shadow will be completely removed. what is going on?

  Let's take a look at the aforementioned<filter></filter> Definition of properties and pay attention to the following details:

  <filter></filter> Elements are never rendered directly; its only purpose is to be referenced , using filter attribute in SVG.

  (My emphasis)

  Therefore, we can conclude that the filter definition of the second SVG graph is applied to the first SVG graph and leads to an error.

  Fix the issue

  We now know the problem and<filter></filter> Properties related. We also know that both SVGs have filter attributes because they use it to create inner shadows on circles. Let's compare the code between these two SVGs and see if we can explain and fix this.

  I've simplified the code for both SVG graphics so that we can see clearly what's going on. The following code snippet shows the code for the first SVG.

  <code><svg height="46" viewbox="0 0 46 46" width="46"><g filter="url(#filter0_ii)"></g><defs><filter height="46" width="46" x="0" y="0"></filter></defs></svg></code>

  The following code snippet shows the code for the second SVG graph.

  <code><svg height="28" viewbox="0 0 28 28" width="28"><g filter="url(#filter0_ii)"></g><defs><filter height="28" width="28" x="0" y="0"></filter></defs></svg></code>

  We can notice that the generated SVG uses the same id attribute id=filter0_ii . Safari applies the filter definition it reads last (in this case the second SVG marker) and causes the first SVG to be cropped to the size of the second filter (from 46px to 28px). The id attribute should have a unique value in the DOM. By having two or more id properties on a page, the browser cannot understand which reference to apply, and the filter properties are redefined in each draw event, depending on the race conditions that cause the problem to appear randomly.

  Let's try assigning a unique id attribute value to each SVG graph to see if this solves the problem.

  If we open the CodePen example in Safari and click the button, we can see that by making it in each SVG graph file<filter></filter> Attributes assign unique IDs, we fixed this issue . If we consider the fact that we have non-unique values ​​for properties like id, this means that this problem should exist on all browsers . For some reason, other browsers (including Chrome and Firefox) seem to handle this edge case without any bugs, although it may be just a coincidence.

  Summarize

  This is a pretty long journey! We go from almost ignoring a seemingly random problem to fully understanding and fixing it. Debugging the UI and understanding visual bugs can be difficult if the root cause of the problem is unclear or complex. Fortunately, some useful debugging strategies can help us.

  First, we simplify the problem by forming assumptions , which helps us eliminate the components (styles, tags, dynamic events, etc.) that are not related to the problem. Afterwards, we isolated the markup and found the smallest reproducible example, which allowed us to focus on a single block of code. Finally, we used a divide and conquer strategy to pinpoint the problem and fixed it.

  Thank you for taking the time to read this article. Before I leave, I want to leave you with a last debugging strategy, which is also covered in Cornell’s CS lecture.

  Remember to take a break between debugging attempts, relax and clean up your thoughts .

  If you spend too much time on bugs, programmers will feel tired and debugging may backfire. Take a break and clean up your thoughts; after rest, try to think about this from a different perspective.

  refer to

  • Cornell University CS 312 Lecture 26 – Debug Technology
  • Debugging Tips and Tips
  • Simplified test cases
  • SVG filter 101