Jest and URL Mocking

I currently ran into a problem while testing some utility functions on a project. We needed to look at the window location to check query string parameters in order to see if our custom parsing was working correctly. Using our favorite JavaScript testing solution, Jest, the standard way of mocking the URL (until it stopped working) was like so:

Object.defineProperty(window.location, 'href', {
  writable: true,
  value: 'https://www.somthing.com/test.html?query=true'
});

At some point, this stopped working based on what I believe was an update to the version of jsdom that Jest uses under the hood. For myself, and other developers needing to mock window.location values, this was frustrating. You can see others have had this same problem, as found on the Jest issues board on GitHub.

After searching that thread (and other postings), I finally found this little gem hidden amongst the posts. In your Jest configuration, make sure to set the following:

"testURL": "https://www.somthing.com/test.html"

Then in your beforeEach() section for your test, change the path as needed by using history.pushState().

window.history.pushState({}, 'Test Title', '/test.html?query=true');

Voila! Now you change out your path for any test, without having to override any jsdom configurations as others suggest in the thread mentioned above. Not sure on which thread I found this solution on, but kuddos to the dev that posted it!

SonarQube With Docker For JavaScript Or TypeScript Projects

SonarQube always seemed a little daunting to me, and I never really gave that much thought to it. How wrong was I! While Static Code Analysis might not find invalid business logic, it does help find security issues and it can sniff out code smells that your team has grown accustomed to. It might seem hairy to set it up for local developers, but it's actually quite easy with the help of Docker and npm!

Things you will need installed on your computer in order set this up:

• Docker
• Node.js and npm
• Yarn (For the Angular example below)

Adding to Your Current Project

Adding SonarQube to your current project is a simple and effective way to help setup quality gates around your current, or new JavaScript or TypeScript codebase. The example below will show you what files you can add to the current Angular GitHub repository without affecting the existing structure of the project. You can use this boilerplate to start off any project.

SonarQube Docker Image

The first thing we will need to do is pull down the latest Docker image of SonarQube to run locally. If you currently are using Docker and Docker Compose for local development, you can just add this image to your existing docker-compose.yml file.

1. Pull down the latest SonarQube docker image:
   docker pull sonarqube
2. If you want to leverage Docker Compose and make the container setup easy to share, all you need to do is the following:
   1. Create a docker-compose.yml file in the root of your project:

      version: '3'
         services:
           sonarqube:
             container_name: sonarqube
             image: sonarqube:latest
             ports:
               - "9000:9000"
               - "9092:9092"

   2. To start the container:
      docker-compose up -d
   3. To stop the container:
      docker-compose stop
   4. To remove the container:
      docker-compose down
3. If you would rather create the new container by hand and not use Docker Compose:
   1. Create the instance of the container:
      docker create --name sonarqube -p 9000:9000 -p 9092:9092 sonarqube
   2. Start the container:
      docker start sonarqube
   3. Stop the container:
      docker stop sonarqube
   4. To completely remove the container from your system:
      docker rm sonarqube

After your container is up and running, within a few moments you should be able to visit http://localhost:9000/ in your browser and see that SonarQube is up and running.

SonarQube Scanner

Now that we have SonarQube setup, it's time to setup the SonarQube Scanner to run against the codebase. The easiest way to install the scanner is by using the npm module sonarqube-scanner. Alternatively, you can scan your code without the usage of node or npm, but it would require setting up SonarQube Scanner by hand. However, I wouldn't recommend it considering how easy it is to setup with npm.

1. Install sonarqube-scanner as a development dependency for your current project:
   • For npm:
     npm install sonarqube-scanner --save-dev
   • For yarn:
     yarn add --dev sonarqube-scanner
2. Create a sonar-project.js file in the root of your project with the following code:

   const sonarqubeScanner = require('sonarqube-scanner');
        sonarqubeScanner({
          serverUrl: 'http://localhost:9000',
          options : {
          'sonar.sources': '.',
          'sonar.inclusions' : 'packages/core/src/**' // Entry point of your code
          }
        }, () => {});

   • For a list of all the different options you can pass into the scanner, visit SonarQube's documentation
   • By default, when scanning a project that has a npm package.json file, the reporting tool will use the package name and version that it finds in the JSON file.
   • You can also pass along your test coverage results into the scanner for SonarQube to parse into it's results. More on that in a future post.
3. In your package.json file, you can update the script section to add the command to execute:

   "scripts": {
        ...
        "sonar": "node sonar-project.js"
      },

4. You can now run the scanner:
   npm run sonar
   • The scan will take a few minutes the first time to complete, but it will be faster for each subsequent run
   • At the end of the run, you will be prompted with the URL to the project's results
5. Be sure to add the .scannerwork directory to your .gitignore file so you don't accidentally commit it
6. Start to reap the rewards of static code analysis for your project!

What does it tell you?

If you are not familiar with SonarQube's analysis, let's pull down a well-known repo and see what it finds. I have a fork of Angular's source on GitHub that you can use for testing:
https://github.com/ryandoll/angular-sonarqube

You can see for yourself how easy it is to get started:

1. git clone git@github.com:ryandoll/angular-sonarqube.git
2. cd angular-sonarqube
3. docker-compose up -d
4. yarn install
5. npm run sonar
6. Visit http://localhost:9000/dashboard/index/angular-srcs in your browser to see the results

The SonarQube results are very interesting for the Angular project. I love the fact that they only have one hour of debt for 12K lines of code! Play around with the results and get familiar with what SonarQube finds. I will start working on a future post about common configurations for SonarQube. For now, the basic setup is a good litmus test for any team to start implementing right away.

Jaded

HTML template engines really challenge my beliefs about the current state of build processes for client-side development. They do simplify building static sites, and help you reduce repetitive HTML throughout your codebase. However, I have a hard time recommending using one all the time because it feels like it adds one more layer to an already growing front end stack. In my mind, HTML is pretty simple enough, so why would we need to complicate things by adding in one more thing? It seems like there is a new tool every week for Gulp or Grunt that developers can't wait to add to a project.

My overall decision on HTML template engines: larger projects with multiple developers can definately benefit by using them. Choosing the right one really depends on your project, as well as the learning curve it might add for the team. I recently had to seriously evaluate the use of Jade on a project, and determine if it would be the right fit for the task.

I coach a few developers at my job who use Jade daily, and always sing it's praise. However, I have always had on main problem with Jade...the syntax. While I could see their point of it enabling you to write less code, using Emmet within your editor of choice made writing HTML easy enough to not warrant a HTML template engine for syntax alone. By not knowing all the benefits of using it, and only focusing on the syntax, I never could warm up to Jade like they could. I figured I would never end up recommending it on any project.

A few weeks back, I started architecting a project at work for a pure client-side piece that would need to be very flexible and modular for future use within a CMS. Knowing that I would already be recommending Gulp as the task runner for the build, I was planning on using Assemble to build out our templates for the site. I had used it earlier in the year with great success. The only downside was that the Gulp plugin for it was currently in alpha, and given the status and rapid speed the project would be iterating at, I couldn't take the risk of an alpha plugin being a part of the build.

After digging around for some other ways of including Assemble into the project, I knew I would have to really start coming to grips that Jade would be the best candidate for the task. It came down to a few points that, given the project, would heavily influence my decision.

Breaking out reusable sections of client-side code is a must for this project. For instance, using a CSS preprocessor like SASS to build mixins for CSS styling is an easy way to keep styles clean and reusable. It is the Extract Method refactoring method that all developers should be using daily when writing code. HTML can also take advantage of this same principle when using Jade mixins and templates. Client-side developers can easily create reusable components for use throughout an entire site. Changing one small Jade template would implement a change across multiple static pages. Later on in phase two, this would not be an issue because the individual components built would be rendered via a server-side CMS. But for phase one, this would be key for the static only site.

Having a team working efficiently during tight deadlines is vital for my company. My team was already very comfortable with Jade, and by letting them continue to work with a toolset they preferred, I would not be hindering their development speed. I had already made a few architectural decisions that were not part of this team's normal workflow, so adding in another change was a risk I was willing to make if the technology itself was worth it. Jade seemed like a win-win: My team would be able to work quickly with a tool they were used to, and the architecture of the build would be solid. Regardless of my initial thoughts, Jade was a solid choice for the project, and I am glad I didn't try to reason my team away from it based on my original disdain on the syntax alone.

One thing to remember using these kind of tools in your workflow: Don't forget to document your templating process/folder structure. Teams that are used to working with a framework like Jade should start documenting mixins and creating an agreed upon style guide. In this project's case, we will be handing over the build process to another team to possibly implement down the road. By documenting what functionality exists within the templates, the learning curve can be reduced for the new team.

Take Jade for a spin in your project, and let me know your thoughts. There are other libraries out there like it to consider (Assemble being the other one I enjoy). Regardless of which you use, learn to take advantage of them for your static site builds.

Style Guides

Style guides can be beneficial to your development process. Most sites that I see worked on do not have a base style guide set up for them for all of the different elements on a webpage. You can find an example of what I am taking about here.

Granted, not all HTML elements will be used on the average site, but it can still be a great thing to test your styles against a single static page for a sanity check if you notice some weird styling happening on your site. Some developers might argue that this would be difficult with the type of site they are building due to multiple module types, and style rules changing out based on what modules are being used. I believe it might be a bit trickier to implement, but it can in fact be done...

I have seen an excellent solution on a project where the developer utilized Gulp to break out each of the different Handlebars templates being used, and with the help of Assemble, create a great site outline that showcased all of the different modules being used on the site. This would automatically be updated when the developer changed any Sass or HTML partial, and the output generated was easily passed off to the client for their review and reference. This is a great use case for leveraging your build process to output something else other than your normal asset flow.

While not the most amazing thing, small items like this added to projects really go a long way when turning over code to a client for them to implement.

Thoughts on Sass

Writing CSS can be tedious. Period. I have been doing web development for over 10 years now, and yet sometimes dealing with a CSS compatibility issue still can give me more heartburn than anything else. With the amount of trouble you can go through with browser compatibility alone, why make your life more difficult by writing all your CSS by hand?

You need a CSS preprocessor.

Most of you are familiar with what a CSS preprocessor does, so I won't go into the details of what they do. But, let's go into all of decisions/thoughts that drive me to recommending Sass as my daily driver.

So which preprocessor do you use? LESS, Sass or Stylus? I work with and coach many web developers at my job, and the flavor of choice that I have seen over the last few years is Sass. I don't think I have seen anyone develop in LESS at all, and I can count on one hand the amount of devs that fire up Stylus as their day-to-day. With that said, I tend to go with what I see the market trending with since I don't see any show stopping differences between them all. Since I am focused on creating front end architecture for projects where code could be passed off to other developers and even other companies quickly, I continue to choose Sass because of its popularity.

However, just because someone says they are using 'Sass' in their project doesn't give you the whole picture. I recently had a .Net developer say that the CMS we were using could handle all the .scss compiling because it was using Sass, and our workflow could be simplified. While his gesture was sincere in wanting to help out with the build process, in the end, that version would cause some issues. More on that later...

Choosing Sass seems like it should be the only commitment that you need to make when choosing a preprocessor. However, that is only the first step. There are several ways of running Sass, and all of them have their advantages and disadvantages. Not only can you choose what framework to run on top of Sass, but you can also choose how you want to run Sass, including which binary to execute against. Let's go into these options for a bit...

After you install the Ruby Gem for Sass, you can be up and running. So in theory, you can just start banging out nested classes and mixins with little setup. But, as all of us front end developers know, using a tool should never be that simplistic. We need more layers to add to our projects! Say hello to Compass.

Compass was the first way I got into running Sass a long time ago. It has some great mixins, and it's ability to create sprites was easy to add into your workflow. All the cool kids were using it, so it just naturally found its way into many projects. Dropping in a simple config.rb to setup your paths in your root directory, and running 'compass watch' in your terminal was dead simple. Plus, that configuration was easy to commit to your version control system so other devs could get up and running without the need of Grunt or Gulp. With all the power that comes with Compass, there lies one big problem...speed. Waiting on your .scss files to compile during your Grunt task was painfully slow. Slow enough to cause you to start drinking...Bourbon.

Bourbon definitely can take the edge off (in more ways than one). Bourbon runs noticeably faster than Compass, since it is just a lightweight library of mixins. While it is installed via a Ruby Gem, the logic itself is all contained within .scss files. Instead of another Ruby process like Compass to execute logic, all you need to do is include the Bourbon files and run Sass like normal. Some of Compass' mixins can easily be replaced with using Bourbon's (in some instances, the mixin names are even the same). If you need some more typography mixins, variables and functions you can add in another library like Bitters to help fill the gaps. So, unless you need all of the functionality of Compass, Bourbon seems to be the clear choice.

However, some people are not a fan of having to add Ruby to their already complex build stack. As I hinted to earlier, developers came up with writing a Sass compiler in C called LibSass and it is currently being used in one of our .Net environments. Not only does this remove the requirement for Ruby, but it also compiles MUCH faster. This can be thrown into a node.js build script using node-sass. Sounds like the perfect fit, right? Well, not exactly. While LibSass might have the edge in speed and portability, it lacks in functionality. Since it is a port, it has often been behind in features compared to the Ruby version, and those minor differences could end up causing headaches for teams depending on it. For instance, running the latest build of Bourbon with LibSass causes errors, due to C version discrepancies on functionality needed by Bourbon's mixins. However, it was recently announced that Ruby Sass is going to wait for feature parity with LibSass before moving forward and will then try to be maintained at the same speed. This is huge news, and will help out the Sass community. It will also get server side developers interested in adding it into their workflow as well since they can avoid the Ruby stack altogether.

So, where does that leave me with my current workflow? It's easy to install LibSass with Homebrew, and then wire that into my Gulp flow. However, the ability to have a nice library like Bourbon that stays fairly updated in my workflow outweighs the pure speed gain of using LibSass. So, it looks like Ruby Sass + Bourbon will be the preprocessor stack that I recommend for the time being until LibSass catches up. Then, I have a feeling a lot of people will start making the shift, including myself.

Living History at Union Station

I just finished up helping out with one of the coolest projects that I have ever worked on at VML during my 9 years here.  This video sums it all up for you, and I highly recommend if you live in Kansas City to download the app and head out to Union Station to try it out! Also, notice the handsome gentlemen posing with Truman at 0:48 in the video ;-)