667
edits
Changes
Created page with "=Fixing a Bug, Adding Tests= This week we're looking at the [https://brave.com/ Brave browser]. We spent time working through a [https://github.com/humphd/browser-laptop/tre..."
=Fixing a Bug, Adding Tests=
This week we're looking at the [https://brave.com/ Brave browser]. We spent time working through a [https://github.com/humphd/browser-laptop/tree/good-first-experience-issue-10554#walkthrough-fixing-a-bug-in-the-brave-browser walkthrough of 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 [http://agiledata.org/essays/tdd.html 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)
* 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.
==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.
* <code>"dog"</code>
* <code>" dog "</code>
* <code>"dog cat"</code>
* <code>" dog cat "</code>
* <code>"https://www.google.ca/search?q=dog"</code>
* <code>" https://www.google.ca/search?q=dog "</code>
* <code>"https://www.google.ca/search?q=dog cat"</code>
* <code>" https://www.google.ca/search?q=dog cat "</code>
For the next set of test cases, you need to '''create a file on disk''' with a space in its filename:
* <code>echo "hello" > "dog cat.txt"</code> (macOS/Linux)
* <code>Echo "hello" > "dog cat.txt"</code> (Windows)
Take note of the '''absolute path''' to your file. On my macOS machine it's <code>/Users/humphd/repos/browser-laptop/dog cat.txt</code>, 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):
* <code>"/Users/humphd/repos/browser-laptop/dog cat.txt"</code>
* <code>" /Users/humphd/repos/browser-laptop/dog cat.txt "</code>
* <code>"file:///Users/humphd/repos/browser-laptop/dog cat.txt"</code>
* <code>" file:///Users/humphd/repos/browser-laptop/dog cat.txt "</code>
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 two 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 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
Read through both files and try to orient yourself. Don't get hung-up on understanding every single line, especially in the Firefox code, which uses lots of internal APIs and [https://en.wikipedia.org/wiki/XPCOM XPCOM base code]. 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 <code>describe()</code> 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 <code>it()</code> test functions. For example, look at <code>describe('getUrlFromInput', function () {...})</code>.
Read the existing tests in order to understand how to structure your own test cases. You can also read the [https://mochajs.org/ mocha docs] and [http://www.chaijs.com/api/assert/ 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 <code>mocha</code>: <code>npm install --global mocha</code>
* build the tests with <code>npm run watch-test</code>
* run the unit tests with <code>npm run unittest</code>
* run a subset of the unit tests by adding a <code>grep</code> expression for the text in the describe/it string: <code>npm run test -- --grep="getUrlFromInput"</code>
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 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:
{| class="wikitable"
! #
! Name
! Git URL to Commit with Fix+Tests (URL)
! Blog Post (URL)
|-
| 1
|
|
|
|-
| 2
|
|
|
|-
| 3
|
|
|
|-
| 4
|
|
|
|-
| 5
|
|
|
|-
| 6
|
|
|
|-
| 7
|
|
|
|-
| 8
|
|
|
|-
| 9
|
|
|
|-
| 10
|
|
|
|-
| 11
|
|
|
|-
| 12
|
|
|
|-
| 13
|
|
|
|-
| 14
|
|
|
|-
| 15
|
|
|
|-
| 16
|
|
|
|-
| 17
|
|
|
|-
| 18
|
|
|
|-
| 19
|
|
|
|-
| 20
|
|
|
|-
| 21
|
|
|
|-
| 22
|
|
|
|-
| 23
|
|
|
|-
| 24
|
|
|
|-
| 25
|
|
|
|-
| 26
|
|
|
|-
| 27
|
|
|
|-
| 28
|
|
|
|-
| 29
|
|
|
|-
| 30
|
|
|
|-
| 31
|
|
|
|-
| 32
|
|
|
|-
| 33
|
|
|
|-
| 34
|
|
|
|-
| 35
|
|
|
|-
| 36
|
|
|
|-
| 37
|
|
|
|-
| 38
|
|
|
|-
| 39
|
|
|
|-
| 40
|
|
|
|-
This week we're looking at the [https://brave.com/ Brave browser]. We spent time working through a [https://github.com/humphd/browser-laptop/tree/good-first-experience-issue-10554#walkthrough-fixing-a-bug-in-the-brave-browser walkthrough of 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 [http://agiledata.org/essays/tdd.html 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)
* 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.
==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.
* <code>"dog"</code>
* <code>" dog "</code>
* <code>"dog cat"</code>
* <code>" dog cat "</code>
* <code>"https://www.google.ca/search?q=dog"</code>
* <code>" https://www.google.ca/search?q=dog "</code>
* <code>"https://www.google.ca/search?q=dog cat"</code>
* <code>" https://www.google.ca/search?q=dog cat "</code>
For the next set of test cases, you need to '''create a file on disk''' with a space in its filename:
* <code>echo "hello" > "dog cat.txt"</code> (macOS/Linux)
* <code>Echo "hello" > "dog cat.txt"</code> (Windows)
Take note of the '''absolute path''' to your file. On my macOS machine it's <code>/Users/humphd/repos/browser-laptop/dog cat.txt</code>, 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):
* <code>"/Users/humphd/repos/browser-laptop/dog cat.txt"</code>
* <code>" /Users/humphd/repos/browser-laptop/dog cat.txt "</code>
* <code>"file:///Users/humphd/repos/browser-laptop/dog cat.txt"</code>
* <code>" file:///Users/humphd/repos/browser-laptop/dog cat.txt "</code>
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 two 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 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
Read through both files and try to orient yourself. Don't get hung-up on understanding every single line, especially in the Firefox code, which uses lots of internal APIs and [https://en.wikipedia.org/wiki/XPCOM XPCOM base code]. 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 <code>describe()</code> 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 <code>it()</code> test functions. For example, look at <code>describe('getUrlFromInput', function () {...})</code>.
Read the existing tests in order to understand how to structure your own test cases. You can also read the [https://mochajs.org/ mocha docs] and [http://www.chaijs.com/api/assert/ 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 <code>mocha</code>: <code>npm install --global mocha</code>
* build the tests with <code>npm run watch-test</code>
* run the unit tests with <code>npm run unittest</code>
* run a subset of the unit tests by adding a <code>grep</code> expression for the text in the describe/it string: <code>npm run test -- --grep="getUrlFromInput"</code>
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 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:
{| class="wikitable"
! #
! Name
! Git URL to Commit with Fix+Tests (URL)
! Blog Post (URL)
|-
| 1
|
|
|
|-
| 2
|
|
|
|-
| 3
|
|
|
|-
| 4
|
|
|
|-
| 5
|
|
|
|-
| 6
|
|
|
|-
| 7
|
|
|
|-
| 8
|
|
|
|-
| 9
|
|
|
|-
| 10
|
|
|
|-
| 11
|
|
|
|-
| 12
|
|
|
|-
| 13
|
|
|
|-
| 14
|
|
|
|-
| 15
|
|
|
|-
| 16
|
|
|
|-
| 17
|
|
|
|-
| 18
|
|
|
|-
| 19
|
|
|
|-
| 20
|
|
|
|-
| 21
|
|
|
|-
| 22
|
|
|
|-
| 23
|
|
|
|-
| 24
|
|
|
|-
| 25
|
|
|
|-
| 26
|
|
|
|-
| 27
|
|
|
|-
| 28
|
|
|
|-
| 29
|
|
|
|-
| 30
|
|
|
|-
| 31
|
|
|
|-
| 32
|
|
|
|-
| 33
|
|
|
|-
| 34
|
|
|
|-
| 35
|
|
|
|-
| 36
|
|
|
|-
| 37
|
|
|
|-
| 38
|
|
|
|-
| 39
|
|
|
|-
| 40
|
|
|
|-
