OSD600 and DPS909 Winter 2018 Lab 6
Contents
Fixing a Bug, Adding Tests
This week we're looking at the Brave browser. We spent time working through a walkthrough of a bug fix together. Now it's your turn to try and fix a bug and add more tests.
In this lab, you are asked to fix a bug in Brave using Test Driven Development (TDD). With TDD, we write tests before we implement the code, and work toward getting our tests to pass. The goals of the lab include:
- Gain experience working on another large open source project
- Learn how to write unit tests via TDD for a bug fix we hope to make
- Learn how to run individual tests in a big project
- Fix a bug in big code
- Read parallel implementations in other large open source projects (Firefox, Chrome)
- Read and Write code written in modern JavaScript
NOTE: you do not need to submit a Pull Request to Brave.
1. Get a Partner
While you're not required to do this lab with a partner, I encourage everyone who wants to do so to go ahead and find one. Open source is best when done in community, and learning how to work with others on debugging and code fixes is a good skill.
After today's lab, you can continue to work on Slack.
2. Build Brave
Begin by forking, cloning, and building Brave. Follow the appropriate instructions for your platform:
- https://github.com/brave/browser-laptop#running-from-source
- https://github.com/brave/browser-laptop/wiki/(setup)-Windows-build-guide
3. The Bug
Modern web browsers allow users to use the URL Bar in order to enter URLs, but also search terms that are meant to be passed to a default search engine. Sometimes a URL can look like a search term, or vice versa, and make it difficult to tell the browser what you want it to do.
For each of the cases listed below, compare the result in Chrome, Firefox, and Brave.
NOTE: I've put double-quotes around the text in order to show you where spaces exist. Remove the double-quotes, and try each one in your test browsers.
-
"dog" -
" dog " -
"dog cat" -
" dog cat " -
"https://www.google.ca/search?q=dog" -
" https://www.google.ca/search?q=dog " -
"https://www.google.ca/search?q=dog cat" -
" https://www.google.ca/search?q=dog cat "
For the next set of test cases, you need to create a file on disk with a space in its filename:
-
echo "hello" > "dog cat.txt"(macOS/Linux) -
Echo "hello" > "dog cat.txt"(Windows)
Take note of the absolute path to your file. On my macOS machine it's /Users/humphd/repos/browser-laptop/dog cat.txt, but it will be different for everyone, and quite different on Windows vs. macOS/Linux.
Now try using your absolute path in the URL bar (i.e., change my path below to yours, but keep the same structure):
-
"/Users/humphd/repos/browser-laptop/dog cat.txt" -
" /Users/humphd/repos/browser-laptop/dog cat.txt " -
"file:///Users/humphd/repos/browser-laptop/dog cat.txt" -
" file:///Users/humphd/repos/browser-laptop/dog cat.txt "
Record any cases where Brave did something unexpected, especially where it deviated from what Chrome and Firefox do.
4. Compare Implementations
Sometimes it's helpful to compare how different projects implement the same feature. You can often learn a lot by reading the code in a project that does what you want, in order to make another do new things.
We'll compare the code for Firefox, Chrome, and Brave:
- The code for fixing URL bar input in Brave is written in JavaScript, see https://github.com/brave/browser-laptop/blob/master/js/lib/urlutil.js
- The equivalent code in Firefox is written in C++, see https://searchfox.org/mozilla-central/source/docshell/base/nsDefaultURIFixup.cpp
- The equivalent code in Chrome is also written in C++, see https://cs.chromium.org/chromium/src/components/url_formatter/url_fixer.cc and https://cs.chromium.org/chromium/src/components/url_formatter/url_fixer.h
Read through both files and try to orient yourself. Don't get hung-up on understanding every single line, especially in the C++ code, which uses lots of internal string APIs, XPCOM code, etc. Instead, try to find clues as to how each one is doing what it does with input strings before converting them to URLs.
5. Add Test Cases
For each of the cases in 3. above where you found a problem, create a new unit test in Brave.
The unit tests for URL parsing in Brave are stored in https://github.com/brave/browser-laptop/blob/master/test/unit/lib/urlutilTest.js
Each describe() block defines a set of tests for a group of functionality in Brave's URL utility code. Find a logical place to add some new it() test functions. For example, look at describe('getUrlFromInput', function () {...}).
Read the existing tests in order to understand how to structure your own test cases. You can also read the mocha docs and assert docs.
6. Run the URL Tests
Tests are really code that needs to be run, and like all code in Brave, you'll have to "build" the test code before you can run the tests.
Follow the instructions at https://github.com/brave/browser-laptop/blob/master/docs/tests.md, specifically:
- install the testing framework
mocha:npm install --global mocha - build the tests with
npm run watch-test - run the unit tests with
npm run unittest - run a subset of the unit tests by adding a
grepexpression for the text in the describe/it string:npm run test -- --grep="getUrlFromInput"
Make sure that your new tests are being run. Because you haven't changed any code yet, your new tests probably fail, which is what we'd expect.
7. Get Your Tests to Pass
Now that we have found our failing tests cases, and written tests, it's time to try and fix the code. Modify the code in https://github.com/brave/browser-laptop/blob/master/js/lib/urlutil.js and re-run your tests. If something fails, go back and fix the code again, re-run the tests, and repeat.
Continue this process until you have fixed the code such that all the tests pass.
8. Submission
Create a branch and commit/push your changes to your fork as a single commit. Get a URL to your commit, which will look something like https://github.com/{your-username}/browser-laptop/commit/83f4763c482bbe0ba07a41711991beee709664bb.
Write a blog post about your experience doing the lab. Here are some things to write about:
- Which URL string cases did you have trouble with in Brave vs. other browsers?
- Did you notice any other interesting differences between browsers and how they handle strings in the URL bar?
- How did you write tests for these cases?
- What did you notice in the Firefox/Chrome code that was both similar and different to the Brave URL handling code?
- What did you have to do in order to get Brave to work the same as other browsers?
- What did you need to learn in order to complete the work?
Please add a line for your blog and GitHub commit in the following table:
