The values

Be a pillar

The team is there for one another, be it to help with day-to-day work or something more personal, we strive to support one-another through good and bad times.

It means understanding that people in the team have strengths and weaknesses and we grow together. We tackle problems head-on as a group to get the best outcomes.

We trust one another that we’re doing the right things at the right times. We avoid micro managing and we assume best intentions when something goes wrong. We work together to find a solution but we accept some of us need space to themselves at times.

Courage to be curious

We challenge ourselves to question how can we make things better? Where can we add value? How do we grow, develop and change? We use curiosity as an antidote to stagnation as a product and as a team.

We stay curious to keep work interesting and stretch ourselves to achieve new things. We’ll get things wrong and we’ll fail but we don’t point fingers and single others out. Instead we come together as a team to fix and make them better.

When mistakes are made we assume they were made with the best of intentions. We keep disagreements respectful and we don’t put others down. If we’re scared to experiment we won’t try new things.

‘Ave a laff!

We work in a light-hearted way, do our best not to let things worry us, keep our humour and find times have a laugh and a joke inside and outside of work.

We like to keep our work exciting and aim to involve all members of the team in our process. We don’t expect people to be code monkeys, pixel pushers or gantt chart trackers.

Fun strengthens the bonds between us and playfulness builds trust. With all this said we take what we do seriously when it matters.

Why values matter

I’ve worked at many companies that have missions and values, but I haven’t worked in teams that had them. It’s not that those teams didn’t have any values but what values they had were implicit and/or ambiguous. Company values have helped coordinate a group of individuals and steered these companies. I think team values can do the same.

A personal favourite company value of mine was Kahoot!’s ‘make learning awesome’. A value so core to the company at the time that it featured promonately at the top of the homepage. I remember several times during discussions where someone may ask the question, ‘is this making learning awesome?’. That wouldn’t just come from the CEO or CPO but from designers, product managers and engineers.

So while reading through some of the opening pages of Sarah Drasner’s Engineering Management for the Rest of Us it inspired me to realise the benefits of what values could bring to a team. I recommend reading the book if you’re also starting out as an engineering manager too.

Defining the values

Following the suggestion outlined in Sarah Drasner’s book I created a Miro with a collection of various words. Some taken directly from the book and some of my own additions. Here’s a few examples of the kind of words that were included. Accountability, fun, vision, trust & curiosity.

Once the collection was gathered, I invited the team to vote for three of the words that most resonated with them. With all the votes cast we then organised a follow-up discussion. We began by digging into the most voted for word to the least and I took notes based on what the team reflected upon.

Here are some of the raw notes I took from that discussion:

Curiosity: Love curiosity in general as it can be a good antidote to judgement. When we’re in a challenging environment it’s healthy.

Fun: The way we work is light hearted. We don’t let things worry us and we get through difficulties. Find time to have a laugh.

Blame free: It’s okay to fail. It’s okay to make mistakes. If you’re scared of making mistakes then you won’t try things, you’ll be less curious and reluctant.

From these notes I then put on my creative writing hat and got to work grouping and distilling the essence of what I had heard into three to five values. Once I was happy with what I had, I shared it with the team to further refine them together. This process repeated until we were all in agreement and we had the three values you read above.

Reflections on team values

I was very happy with the values that we defined as a team. I think they captured how the team was at the time and I found myself referring back to them on occasion during one to ones with various members of my team.

I do believe there was more I could have done to have made them more impactful on a regular basis. When a worry was flagged to me from a member of the team, I could have cited our team values back to them as a way of saying, you don’t need to worry, as a team we expect these things, we understand them and we’ve accounted for them in our values.

Onboarding new people to the team could be made easier by providing them with the team values ahead of them joining. I think that could give them an idea of the ways we work and what behaviours they can expect.

Values don’t need to be set in stone. Teams change, companies change and people come and go. While values form a good basis for working together, I think they should be adaptable. If you’re a start-up or rapidly experimenting then some of your values may reflect this but when you’ve matured you might find the same values no longer reflect as well as they once had. I think it’s okay to repeat the process and define new ones.

So that’s what I have on values. I hope this got you to consider your team’s values and whether codifying and making them explicit would be beneficial to you. I know I will certainly look to define future values with future teams.

I recently made the switch from React over to Svelte (something I might write about in the future but that’ll need to be for another day).

While working on a personal project I am learning about Svelte & SvelteKit as I go while mostly rely on my existing React knowledge and then trying to understand the Svelte approach when things don’t work as I expect them to.

I wanted on a reusable List component. The idea of this component is that it takes a list of items as a prop and then loops over them creating a HTML structure of a ul with content contained within lis.

The benefit of this component is that you can put anything you want within the li but the styling of the list has already been defined.

It’s pretty straightforward but making this component in Svelte was a little more involved than I was expecting it to be and required the use of some Svelte that I had not seen before so I thought I’d document what I needed to do.

React

First let’s look at how I would typically build this kind of component in React. Our List component is responsible for looping over a list of items it receives via props. We do this using the map method and returning a new list with an li and the item inside:

import { type ReactNode } from 'react'

type Props = {
  items: ReactNode[]
}

export const List: React.FC<Props> = ({ items }) => {
  return (
    <ul style=>
      {items.map((item) => (
        <li style=>{item}</li>
      ))}
    </ul>
  )
}

The basic component we want to put within our li for this example is a Card component. It simply has some padding and border and takes some copy via props:

type Props = {
  copy: string
}

export const Card: React.FC<Props> = ({ copy }) => {
  return (
    <div style=>{copy}</div>
  )
}

To then use our List component we just need to add a list of React components, in this case Card. The cards and their copy will then be rendered within our ul and lis:

root.render(
  <React.StrictMode>
    <List items={[<Card copy="a" />, <Card copy="b" />, <Card copy="c" />]} />
  </React.StrictMode>
)

This will then show a list of cards with a, b & c in the browser. You can view the example in Codesandbox.

Svelte

So how do we do the same in Svelte? Well it’s a little different than it is in React. We need to make use of a special Svelte element called svelte:component.

This special element allows for dynamic component rendering. Using the this prop we can tell the svelte:component what component it needs to be. We can then pass any props we want to it.

Since we can’t know what props will be needed for all components ahead of time we need to spread all the props and leave the component to figure it:

<script>
  export let items;
</script>

<style>
  ul {
    margin: 0;
    padding: 0;
    list-style: none;
  }

  li + li {
    margin-top: 1rem;
  }
</style>

<ul>
  {#each items as item}
    <li>
      <svelte:component this={item.component} {...item} />
    </li>
  {/each}
</ul>

Our Card component in Svelte is very similar to the React version. It expects a copy prop to be passed so that it can render it within a div and applies some basic styling:

<script>
  export let copy;
</script>

<style>
  div {
    padding: 1rem;
    border: 1px solid grey;
  }
</style>

<div>
  {copy}
</div>

Usage of the List component then requires us to pass a list of objects. One that states which component to use; in our case, Card and then any of the expected props that it needs.

It’s a little more verbose compared to the React version but in principle, it’s the same:

<script>
  import Card from './Card.svelte'
  import List from './List.svelte'

  let items = [
    {
      component: Card,
      copy: 'a'
    },
    {
      component: Card,
      copy: 'b'
    },
    {
      component: Card,
      copy: 'c'
    }
  ]
</script>

<main>
  <List {items} />
</main>

This will then show a list of cards with a, b & c in the browser. You can view the example in Codesandbox.

Hopefully this is helpful for others since it took a bit of googling to find out how to do this kind of component in Svelte.

VSpace is a utility component that I learned of and used quite a bit during my time at Bulb. Essentially it provides vertical space/rhythm to its direct descendants. You can read more about VSpace on the Bulb design system website.

It’s a useful component for controlling layout without writing lots of styling and it is versatile as it allows you to render it as any element of your choosing using an as prop and provide different spacing tokens. The one thing it relies heavily on is lobotomised owls.

Lobotomised owls?

Lobotomised owls is a slightly odd looking combination of CSS selectors. The CSS selector is * + * which according to the author (who also briefly worked for Bulb) thinks it looks like an owl that’s had a lobotomy.

A quick break down of this selector; The * is the universal selector which means it will match against any element, followed by the + which is the adjacent sibling combinator and finally another universal selector. All this together means, whatever the first element is, apply some styling to whatever sibling element follows after it and any element after that and so on and so on.

Vanilla Extract?

So what’s the deal with Vanilla Extract? It describes itself as:

It seems like a cool library but today is my first time using it. One thing that makes creating the lobotomised owl selector difficult with Vanilla Extract is the bit about “locally scoped classes, variables and themes”.

Because the selector relies on affecting child elements, that’s considered a no, no to Vanilla Extract, although they do provide some escape hatches that allow it to be done but figuring out how was quite an interesting bit of learning.

Implementation

The VSpace React component

/**
 * VSpace.tsx
 */

import { createElement } from 'react'
import * as styles from './VSpace.css'

type Props = React.PropsWithChildren<{
  spacing?: keyof typeof styles.spacings
  as?: keyof React.ReactHTML
}>

export const VSpace: React.FC<Props> = ({
  children,
  spacing = 's_1',
  as = 'div',
}) => createElement(as, { className: styles.spacer[spacing] }, children)

The component takes three props, children which are any child components. as is used to change the element type that will be rendered. Since this is used for layout I default to div. Lastly spacing which represents a design token for our spacings. In this example we default to s_1 which maps to 1rem. I’ve used createElement as I find it makes it easier to use as with and I’ve also explicitly not allowed additional props to be passed in.

Styles

/**
 * VSpace.css.ts
 */

import {
  createVar,
  globalStyle,
  style,
  styleVariants,
} from '@vanilla-extract/css'

export const spacings = {
  s_0_25: '0.25rem',
  s_0_5: '0.5rem',
  s_1: '1rem',
  s_2: '2rem',
  // …
}

/**
 * CSS custom property that will be passed to the lobotomised owl as margin-top.
 */
const spacing = createVar()

/**
 * Base styling to compose with the variants.
 */
const base = style({})

/**
 * The spacer gets the custom property and assigns the desired spacing to it.
 */
export const spacer = styleVariants(spacings, (spacingKey) => [
  base,
  {
    vars: {
      [spacing]: spacingKey,
    },
  },
])

/**
 * Global styles are required due to affecting children and so break the
 * component isolation enforced by vanilla extract.
 */
globalStyle(`${base} > * + *`, {
  margin: `${spacing} 0 0`,
})

Map is a common higher order function which takes a list, loops over said list and applies a given function against each item creating a new list from the results. For example, say we have a list of numbers [1, 2, 3] and we have a function that adds one to a number number => number + 1, when we loop over our list with this function we will have a new list containing [2, 3, 4]. Read more about Map on Wikipedia

Writing a map function in Rust

Something to note is that Rust ships its own Map function in its standard library but as a learning exercise I feel a good way to learn the language is to implement things you already know. So this is my current understanding of how to implement map in Rust. Not sure it’s the most performant it could be or even very elegant code but I think it’s readable for the most part.

fn map<A, B>(list: &Vec<A>, mapper: Box<dyn Fn(&A) -> B>) -> Vec<B> {
    let mut mapped: Vec<B> = Vec::new();

    for item in list {
        mapped.push(mapper(item));
    }

    mapped
}

fn main() {
    let numbers: Vec<u32> = vec![2, 3, 4];
    let squared: Vec<u32> = map(&numbers, Box::new(| x: &u32 | x * x));

    println!("Mapped {:?}", squared); // [4, 9, 16]
}

So lets break this down and share my current understanding of how this works. I’ll skip over main as its purpose is to run the program and simply print the result which is [4, 9, 16].

Passing values by reference or borrowing

One unique aspect of Rust is its ownership system. We don’t want to give the map function the ownership of the original list, in the example numbers. The reason for this is we expect to return a new list which would mean that numbers would go out of scope and be cleared. If we passed the original list then you’d not be able to use the after calling map with it. To avoid this we pass it by reference.

// list is owned by map.
fn map<A, B>(list: Vec<A>, mapper: Box<dyn Fn(A) -> B>) -> Vec<B> {
    // …
}

// list is borrowed as denoted by &Vec<A> which also means that the 
// closure that is provided as a mapper fn receives an item value 
// also by reference.
fn map<A, B>(list: &Vec<A>, mapper: Box<dyn Fn(&A) -> B>) -> Vec<B> {
    // …
}

Box and dynamic values at runtime

For values that cannot be determined (maybe sized) at runtime, you need to wrap it in Box along with the dyn keyword. This means this value will be allocated to heap memory rather than the stack. This makes writing the closure function a bit annoying and likely less performant. I am sure there’s ways around this but I am not sure how right now.

Box::new(| x: &u32 | x + 1)

Using Rust’s map function

To do the above with Rust’s built in map function would look something like this:

fn main() {
    let numbers: Vec<u32> = vec![2, 3, 4];
    let squared: Vec<u32> = numbers.iter().map(|x: &u32| x * x).collect::<Vec<u32>>();

    println!("Mapped {:?}", squared) // [4, 9, 16]
}

So let’s dig into this. We take our vector which is a collection, we turn it into an iterator by calling .iter(), once we have an iterator we can call .map() which returns a new iterator so finally we call .collect() to turn it back into a collection.

Some context

Before jumping in I just wanted to add some context. I am approaching the architecture of this project in a micro-service-like way. The project is a single mono-repo broken into clients (UIs), services (APIs) and utils (Shareable code). I think the benefit to this is approach will be to keep different parts of the project isolated and individually deployable, however it could always be bundled as a single image (I think so anyway, I guess I’ll find out).

Below is a snapshot of the rough shape of the project with some files not shown as they’re mostly configuration:

clients
utils
services ↴
··service A ↴
····src ↴
······api ↴
········api
········routes
········controller
········service
······db
······config
······main
····tests ↴
······integration
····.env
····docker-compose.yml
····package.json

Docker Compose configuration file

So in keeping with the idea of isolation each service will have it’s own DB (again, potentially since each service could be configured to point to a single DB at deployment) I opted to use Docker Compose to easily grab a PostgreSQL image and spin it up when the service starts. Here’s a look at the docker-compose.yml as I have it right now. I’ll walk through and point out things that might be of interest if you’re not familiar with using Docker Compose.

version: '3.9'

services:
  db:
    image: 'postgres:14.1-alpine'
    container_name: service_a_db
    restart: always
    environment:
      POSTGRES_USER: service_a
      POSTGRES_PASSWORD: super_secret
    ports:
      - 5000:5432

Config breakdown

• version
  The version is optional since v1.27.0 of Docker Compose however I feel it doesn’t hurt to include it.

• services
  This is a list of services you want to spin up using Docker. In my case I just want a single service, a DB, that service being the one I’ve named db. You can call yours Jim if you prefer.

• image
  This if the Docker image I want to create a container from. It’s an official image on DockerHub for PostgreSQL. I’ve used the version tag so I can be certain that as new versions of PostgreSQL are released I am still developing and testing against the same as what my production environment is using. alpine denotes that this is a minimal sized container.

• container_name
  This is optional but it is handy to help find your container once it’s up and running. If you omit it you’ll be given a default name. To check this is set correctly you can run the following command; docker ps. docker ps shows you a list of containers. You should see something like this:

  CONTAINER ID   IMAGE                  COMMAND                  CREATED        STATUS       PORTS                    NAMES
  51f30726c405   postgres:14.1-alpine   "docker-entrypoint.s…"   26 hours ago   Up 9 hours   0.0.0.0:5000->5432/tcp   service_a_db
  

• restart
  I’m honestly not sure why this should be set to always after reading the Docker Compose docs but it is set this way according to the Docker Hub example but I’ll go with what they suggest.

• environment
  The environment allows for passing environment variables into the container. POSTGRES_PASSWORD is required by the official PostgreSQL image. For security reasons there is no root user when the DB starts. For my needs I’ve included a specific user with POSTGRES_USER. This also has the effect of creating a database of the same name. If this variable is omitted then postgres will be used instead.

• ports
  The ports expose network ports within the container to an “outside world”. By default, PostgreSQL runs on port 5432. In the case above I’ve mapped 5000 as each of my services will increment, so Service A’s API will be 8000 with the DB on 5000 while Service B will be 8001 & 5001. Not exposing these ports when I initially wrote the config lead to which you can read about in Troubleshooting.

Working with the DB service

Now that we’ve got our config we’re ready to get our DB started. To do this we can run the command docker-compose up. This command will build the image, create a container and start it. You’ll get a bunch of output but ideally you’ll see a final log that looks something like the following:

service_a_db  | 2021-12-31 10:07:50.025 UTC [1] LOG:  database system is ready to accept connections

You can optionally run this in the background using the detach flag; -d, e.g. docker-compose up -d. While this will let you use your terminal you’ll not see the logs. At times though you might want to see logs and you can do this with the following command; docker logs [CONTAINER_NAME] for a one off look or with an optional follow flag; -f to give you realtime updates.

To stop the service and remove any data you can run docker-compose down.

If you want to mess around with the DB running in the container there’s two ways I do this. The first way is to use Docker’s exec command to call psql. Using docker exec -it [CONTAINER_NAME] psql -U [POSTGRES_USER], i.e. docker exec -it service_a_db psql -U service_a or you can use the DB’s connection string, i.e. docker exec -it service_a_db psql postgres://service_a:super_secret@localhost:5432/service_a. This should then give you access to psql tooling.

Another approach is to access the container’s shell and then access psql with it. This offers you more access to the container environment beyond just psql. To do this use docker exec -it /bin/bash and then connect to the DB in the same way as above.

Connecting to DB in Node

Now that the service is running we can attempt to connect the Node API to the running instance. For this I use Slonik. First of all though we’ll want to add the DB’s connection string to the env variables for the API. I am using dotenv so I just need to edit my .env file to include it.

DB_CONNECTION_STRING=postgres://service_a:super_secret@localhost:5000/service_a

Notice that we’re using the port that we set in docker-compose.yml and not the one that PostgreSQL uses by default. This tripped me up a bit an I’ll cover it in troubleshooting. Once the env variable is added, I access it using a config.ts which looks something like this:

import { MissingConnectionStringError } from './errors'

const { DB_CONNECTION_STRING: dbConnectionString } = process.env

if (!dbConnectionString) {
  throw new MissingConnectionStringError()
}

export const config = {
  dbConnectionString,
} as const

A couple of things to note here. I’ve created a custom error to be thrown if the env variable has not been loaded correctly. I then export a config object with the connection string so it can be accessed more easily and mark the config as const to avoid any unexpected attempts to overwrite the values within it. Using as const will mark each property of the object as readonly.

Finally I have a db.ts which is where we’ll hook up Slonik to our DB and export a pool that will allow us to connect and query the DB. The pool can then be imported into our services to make queries against the DB.

import { createPool, type DatabasePool } from 'slonik'
import { config } from './config'

export const pool: DatabasePool = createPool(config.dbConnectionString)

Troubleshooting

Not exposing ports

The first time I did this I didn’t expose the ports in the Docker compose config and my connection string used 5432 which resulted in a red herring of an error message. I would get the following error stack in my API:

/…/node_modules/slonik/src/factories/createConnection.ts:128
  throw new ConnectionError(error.message);
                 ^
ConnectionError: password authentication failed for user "service_a"
  at createConnection (/…/node_modules/slonik/src/factories/createConnection.ts:128:15)
  at processTicksAndRejections (node:internal/process/task_queues:96:5)

This lead my down the path of wondering whether I had configured the environment variables for PostgreSQL correctly but it was resolved by exposing the ports correctly.

Ramda is full of useful functions and add is the first in the list. It helps by being one of the most simple functions (there are others that are even smaller). The aim of these little posts are to visit each function at a time and better understand how it is written and why it is useful.

Add is one of the more straightforward functions in Ramda. It is used to add two numbers together. Like all functions in Ramda it is automagically curried and and can be written in few ways. You can pass a single value and create a whole new function, pass both arguments to get a new value or call add twice with a single argument each time to get a value. Take a look below for some examples:

const add2 = add(2) // (x) => y
const sumA = add(2, 2) // 4
const sumB = add(2)(2) // 4

Example use-cases

Add a standard fee to a product price:

const bookingFee = 1.99
const calculateTotal = add(bookingFee)
const total = calculateTotal(19.99) // 21.98

A ticket for every time someone joins a queue:

const increment = add(1)
const peopleQueueing = 12
const takeTicket = (peopleQueuing) => increment(peopleQueuing)
const yourNumber = takeTicket(peopleInQueue) // 13

How to write your own

You can always check out Ramda’s implementation but they have an entire library to work with and writing your own you might not have those benefits. Since I am doing this as a process for learning we’ll take a look at a simple implementation and then a curried version.

Simple

The simple version of add will be a function that takes two arguments and adds those numbers together.

// es6
const add = (x, y) => x + y

// es5
function add(x, y) {
  return x + y
}

// TS
const add = (x: number, y: number): number => x + y

Curried

The curried version is very similar to the above. If you don’t know what currying is there is a chapter on currying in the Mostly Adequate Guide to Functional Programming book. If you prefer short videos then FunFunFunction’s episode on currying is worth a watch.

// es6
const add = (x) => (y) => x + y

// es5
function add(x) {
  return function add(y) {
    return x + y
  }
}

// TS
const add =
  (x: number) =>
  (y: number): number =>
    x + y

At just a little over 50% requiring code reviews to be part of their team’s engineering process from a pool of nearly 1900 respondents, perhaps you can understand my surprise.

I am a big believer in code reviews, in particular; paired code reviews. I have found them to offer great benefits and in this article I want to outline three of those I think are the most important. With pros must come cons and there are, so I will touch upon them also.

The original tweet & poll from Mattias Petter Johansson

Why Do Code Reviews

To give a bit more context, I’ll start by outlining the process of code reviews that I am familiar with. Many of the developers are comfortable with working in isolation. We’ll discuss approaches to solving problems and provide help to one another when called on but we rarely pair program. However, we do code review in pairs. All developers are encouraged to be the code reviewer, regardless of their seniority.

Knowledge Share & Developer Growth

This is, I believe, one of the most important reasons to code review. One scenario might be that the reviewer’s skillset is more expansive than the developer’s which allows for the opportunity to offer improvements, guidance and insights. This is an excellent way to boost a skill you may not be as strong in, at least not yet. Or, perhaps, the developer in need of a review may be more senior and the reviewer junior or vice versa. This is a fantastic opportunity for one developer to pass on any pearls of wisdom to another. In fact it’s a win-win situation and a learning loop. The developer will have learnt of new techniques and can pass this knowledge on to others. Both developers get to learn, teach and grow.

Onboarding, Practices & Culture

Introducing new developers to your team, explaining workflows, processes and the way you’d like to work together can take time. Doing code reviews across the wider team will allow newcomers to meet other developers and also learn about the engineering teams practices without having to go through pages of documentation. It’s certainly more fun, and, as a consequence, they get the knowledge needed in a faster and more engaging way.

We work in distributed teams so jumping on a hangout and sharing a screen has the benefit for all of us to stay in regular contact and hopefully feel like just a single engineering team.

Quality Assurance

Code review is a great form of quality assurance, two heads are better than one and when you’ve been working on something for some time, you may have missed something. A bug that slips through that you’re sure you would have noticed. Having a fresh pair of eyes look through the code will help to catch that sneaky one.

A lot of the time just the practice of going over your code with other developers will shine a light on problem code. Does this make sense to you? Could this be improved? Are there alternatives that we should consider? These control questions can be asked to the reviewer. After a long day I’ve gone back to code and not been able to make sense of it myself and so here’s a chance to put that right. As I stated in the beginning of this article, the system is not perfect. Let’s look at the cons and discuss ways to deal with them.

Why Not to do Code Reviews

So with the good must come the bad. I’d be disingenuous if I didn’t cover them but with that said I don’t believe that any of the bad is enough of a reason to not code review.

Time

When you’re using your time to look over someone else’s code you’re not going to be working on your own. Of course in the grand scheme of things, if you’re pushing fewer bugs and you’re creating less tech debt you’re potentially saving time in the long run. However, in an agile environment with a bunch of tickets waiting to be done I can see how it might feel like it’s hard to spend that time. You can try and time box the code reviews. Smaller commits with good descriptions of the changes should help keep the code reviews short. Besides, completing small tasks one after another is a good feeling.

Only Human

While having someone else to look over your code can lead to finding bugs early and even improving it before it goes into production, it’s definitely not infallible. We’re only human and so mistakes can slip through. Code reviews won’t replace an acceptable test suite and even a second QA process that will check your product, but they’ll hopefully catch issues sooner.

To Sum Up

Using code reviews in my current position has given me the opportunity to learn and teach. I can share my knowledge to others when I review their code and I regularly learn something new when people review my code. Even if it’s not a perfect system, it has led to great, constructive debates and made my day-to-day job of coding more collaborative, engaging and fun.

A pattern library is a collection of reusable components that can be used together to create an application. I tend to focus on web applications but a pattern library shouldn’t be limited to the web. I like to imagine a pattern library as a big box of Lego, full of blocks of different shapes, colours and usages that I can build lots of cool things with.

An example would be Mailchimp’s excellent pattern library and FutureLearn’s extensive pattern library. Both split their libraries modularly. Grid system, typography, forms, navigation and more. They show use cases, markup and notes left by designers and developers. A developer implementing a component into an app has all the information they need.

The way I approach creating a new pattern library is to look at the existing product (if there is one) or designs and discern common patterns, hence a pattern library. Patterns of an app are pieces that look or function very similar to other elements. I split these parts out as a component and begin to normalise them. Here’s a rather specific example:

Very rough and specific but hopefully a useful

Even at this early stage we can see a pattern (with more designs we’d certainly see more). The buttons are slightly different but both look and work in a similar way, as in I click one and it does some sort of action.

My approach would be to give this pattern a name, e.g. .btn, .action-button or simply .button and this naming should be agreed by the team. Then I’d discuss this with a designer. I’d try and reach an agreement on what could be normalised, such as border-radius, background-color or height.

Doing so makes the naming of components become much easier. When it comes to CSS styling, this process aids with BEM naming or through CSS module composition. We might end up something like this:

$button-colours: (
  default: #2a8fbd,
);

.action-button {
  @include button-reset;

  height: 2rem;
  padding: 0 0.5rem;
  background: map-get($button-colours, default);
  border: 1px solid darken(map-get($button-colours, default), 10%);
  border-radius: px2rem(3px);

  &--square {
    width: 2rem;
  }

  &--large {
    height: 3.5rem;
    padding: 0 1rem;
  }

  &--square#{&}--large {
    width: 3.5rem;
  }
}

Once you have your pattern library, at the very minimum it needs to be spread throughout the company. Both designers and developers need to be aware of it and work closely with it. This leads to a shared language between designers and developers but also other members of the team.

If a designer is creating a new section of an app, they should be wire-framing or prototyping with components from the pattern library, not creating completely new designs. Iterations and feedback can be made faster and functionality isn’t a concern as it will already have been defined.

For developers, the creation of reusable components means that concerns about the look and functionality would have been previously addressed so the implementation and testing can be the focus.

These are what I believe are some great benefits that come from the use of a pattern library.

• A shared language throughout the company. I think this can be understated but when everyone shares the same language, communication is much easier.
• Spend more time prototyping, implementing, testing and iterating. When you understand the patterns it takes less time to prototype and implement aspects of an app. Adding a new section? You shouldn’t need to worry about how buttons and inputs look and work.
• It acts as documentation. Giving examples, markup, use cases and notes makes it much easier to document the architecture of an app and is especially useful for new developers joining the team.
• It’s an ongoing process. A pattern library should never be finished. Components can safely be improved upon or redesigned within the confines of the pattern library before affecting the app itself.
• Visual regression testing. Visual regression testing can be made on each component individually. You have a greater safety net when making changes to a component since you will have more granular diffing.
• Style in isolation. Because your components is a single piece of an app you should style them on their own. A component should look good and function correctly without the context of other components.

Here a few other articles you may find useful in your learning of pattern libraries.

• Getting Started with Pattern Libraries — Anna Debenham
• Building our First Pattern Library — Alla Kholmatova
• Atomic Web Design — Brad Frost
• How and why to Create a Pattern library — Paul Boag

I won’t go on about Sass maps, they’ve been around since Sass 3.3 (7th March 2014) and I am sure me raving about their usefulness is not going to be of much interest. What I did want to write about, which I hope, is going to be interesting is a little experiment into how far I could take Sass maps and what I learnt from doing so.

Let the Experiment Begin!

Using a preprocessor is all about simplification. “How can I get the most done for as little effort?”. That’s why we now have loops, functions, mixins, nesting and variables in our CSS now (there’s plenty more but you get the idea). Maps are just one more tool in the Sass shed. Take this button example below:

.btn {
  width: 150px;
  height: 40px;
  background: grey;
  border: 1px solid darken(grey, 10%);
  color: white;
  display: inline-block;
  vertical-align: bottom;

  &:focus {
    outline: none;
  }

  &:hover,
  &:focus {
    height: 38px;
    margin-top: 2px;
    background: darken(grey, 10%);
  }

  &:active {
    height: 36px;
    margin-top: 4px;
  }

  &--primary {
    background: blue;
    border-color: darken(blue, 10%);

    &:hover,
    &:focus {
      background: darken(blue, 10%);
    }
  }

  &--warning {
    background: red;
    border-color: darken(red, 10%);

    &:hover,
    &:focus {
      background: darken(red, 10%);
    }
  }

  &.is-active {
    animation: glow infinite 3s;
  }
}

chars : 667 | words : 75 | lines: 49

PropaSass Button example 01

We can use Sass maps and lists here to DRY things up a little and make our button class a little more maintainable.

$states: (
  hover: (
    38px,
    2px,
  ),
  focus: (
    38px,
    2px,
  ),
  active: (
    36px,
    4px,
  ),
);

$modifiers: (
  primary: blue,
  warning: red,
);

.btn {
  width: 150px;
  height: 40px;
  background: grey;
  border: 1px solid darken(grey, 10%);
  color: white;
  display: inline-block;
  vertical-align: bottom;

  &:focus {
    outline: none;
  }

  &:hover,
  &:focus {
    background: darken(grey, 10%);
  }

  @each $state, $styles in $states {
    &:#{$state} {
      height: nth($styles, 1);
      margin-top: nth($styles, 2);
    }
  }

  @each $modifier, $colour in $modifiers {
    &--#{$modifier} {
      background: $colour;
      border-color: darken($colour, 10%);

      &:hover,
      &:focus {
        background: darken($colour, 10%);
      }
    }
  }

  &.is-active {
    animation: glow infinite 3s;
  }
}

chars : 757 (+90) | words : 85 (+10) | lines: 49 (N/A)

PropaSass Button example 02

We’ve added a few characters and some words but I believe there are some benefits. In my opinion we have abstracted out the modifiers to the top of our class so from a basic overview we can see how our button styles will change on state and how our button is being modified.

Changing state or adding new modifiers should be easy peasy and won’t require us to make changes to our button class. But what if we took this just a little further?

It’s Alive, IT’S ALIVE!

I think perhaps it’s best to show an early idea of what I am choosing to call PropaSass (The idea of passing ‘props’ is taken from React and a play on words of proper or as some fellow East Londoners may pronounce it, ‘propa’.)

We need to define a function and a couple of mixins which should be added with your other functions and mixins. These handle looping and conversion.

@function class-name($prefix, $modifier) {
  @if not $prefix {
    $prefix: '';
  }

  @if not $modifier {
    $modifier: '';
  }

  @return $prefix + $modifier;
}

@mixin style-with($styles) {
  @if not $props {
    @warn 'No styles were defined';
  }

  @each $style in $styles {
    #{nth($style, 1)}: nth($style, 2);
  }
}

@mixin modify-with($props) {
  @if not $props {
    @warn 'No props were defined';
  }

  @each $prefix, $modifiers in $props {
    @each $modifier, $styles in $modifiers {
      &#{class-name($prefix, $modifier)} {
        @include style-with($styles);
      }
    }
  }
}

So once we have these helpers defined, let’s re-write our button class and put those helpers to work!

$props: (
  &: (
    ':hover, :focus': (
      height: 38px,
      margin-top: 2px,
      background: darken(grey, 10%),
    ),
    ':focus': (
      outline: none,
    ),
    ':active': (
      height: 36px,
      margin-top: 4px,
    ),
  ),
  '--': (
    'primary': (
      background: blue,
      border-color: darken(blue, 10%),
    ),
    'primary:hover, primary:focus': (
      background: darken(blue, 10%),
    ),
    'warning': (
      background: red,
      border-color: darken(red, 10%),
    ),
    'warning:hover, warning:focus': (
      background: darken(red, 10%),
    ),
  ),
  '.is-': (
    'active': (
      animation: glow infinite 3s,
    ),
  ),
);

.btn {
  width: 150px;
  height: 40px;
  background: grey;
  border: 1px solid darken(grey, 10%);
  color: white;
  display: inline-block;
  vertical-align: bottom;

  @include modify-with($props);
}

chars : 787 (+120) | words : 84 (+9) | lines: 44 (-5)

PropaSass button example 03

I want to point out that I am not suggesting this is a good way to write Sass, or that this should even be used but I quite like it and I think it has benefits. We define our base styles and then define our modifier sass map called props, passing them to our new modify-with mixin. We now have a clear separation of how our props will change our button class’ styling. We also avoid any confusing nesting.

Making changes are a little easier and if we want to change how our base style is modified, let’s say for example you really dislike BEM naming (c’mon double hyphen isn’t so bad) you can make that change easily.

One arguable drawback is now though we are defining CSS properties with a weird, Frankenstein’s monster, JSON-like syntax written using a Sass map. (Sass Map Notation? SAMN? Salmon syntax? Whatever, I kinda like it but then I am the mad scientist that created it.)

A less verbose look in an editor: chars : 719 | words : 86| lines: 28 |

Summary

I never set out to create anything along the lines of what you see above (although if you think it’ll be useful, please let me know). I saw a new feature (to me at least) and I wanted to see how far I could take it.

I think this little exercise has given me insights in to how effective the use of maps can be and how they can DRY up Sass. I’d also recommend this kind of experimentation when you find a new feature as there were plenty of problems that needed solving and meant gaining knowledge of new built in SassScript functions that I hadn’t used befor such as map-get and nth.

If you’d like to see the code, I’ve created a Github repo and if you’ve liked what you’ve seen and read, feel free to contribute and improve PropaSass.

Author notice!

At the time of writing this very line I have not even installed WebDriver.IO and so please do not consider this a ‘how to’, it’s simply my experience using WebDriver.IO along with Jasmine and PhantomJS (which I am also fairly unfamiliar with), for good or bad.

If you find anything within this article that is incorrect or could be improved upon, please don’t hesitate to let me know. I am still new to testing so any help is greatly appreciated. Thank you!

Installation

The documentation asks you to install Selenium Server Standalone via Curl but I used HomeBrew since I am working with Mac OSX and the version is the same as the Curl version so I assume it’s safe to do so.

HomeBrew will also give you some instructions on how to start the Selenium Server. Since I am trying it out I don’t want Selenium Server to run every time I start my Mac so inside terminal I will just use:

$ selenium-server

Doing so will fire up Selenium Server, ready for use. To install WebDriver.IO it’s as easy as using NPM (Node Package Manager).

Using the terminal:

//  adds webdriverio to a local project
$ npm install webdriverio

Inside of test.js:

var webdriverio = require('webdriverio')

Once the server was up and running I put together an exact version of the demo from WebDriver.IO’s documentation. Something to note, the first time I ran the test it took quite some time for it to return the value, subsequent tests were noticeable quicker.

On the whole installation was very quick and very simply which is always good in my book. Now though I want to add it to a potential test suite.

Writing my first tiny Jasmine, WebDriver.IO & PhantomJS spec

I am going to be using Jasmine as my spec framework, I am familiar with RSpec and Jasmine seemed like a natural JavaScript alternative and also WebDriver.IO supports it (min version 2.0), I’ll also be using PhantomJS to have a browser to run the specs in. If you haven’t already installed them, it’s simply a case of using NPM again. Also to gain access to WebDriver.IO’s cli tools and test runner you’ll need to add it as a global package.

$ npm install -g webdriverio jasmine phantomjs

At this stage I don’t plan on adding it to an existing project because I want to learn more of the WebDriver.IO API and I want to start small so I am going to create a single spec file and create a WebDriver.IO config file.

//  creates a jasmine framework file structure
$ jasmine init

//  goes through the process of create a webdriver.io config
$ wdio config

// subsequent config (minus comments)
exports.config = {
  specs: ['spec/**/*.js'],
  exclude: [
    // 'path/to/excluded/files'
  ],
  capabilities: [
    {
      browserName: 'phantomjs',
    },
  ],
  logLevel: 'silent',
  coloredLogs: true,
  screenshotPath: './errorShots/',
  baseUrl: 'http://adamjohnston.co.uk',
  waitforTimeout: 10000,
  framework: 'jasmine',
  reporter: 'dot',
  jasmineNodeOpts: {
    defaultTimeoutInterval: 5000,
    expectationResultHandler: function (passed, assertion) {
      // do something
    },
    grep: null,
    invertGrep: null,
  },

  onPrepare: function () {
    // do something
  },

  before: function () {
    // do something
  },

  after: function () {
    // do something
  },

  onComplete: function () {
    // do something
  },
}

So with that said, I am going to test my portfolio site. I have a menu button that when clicked will show a list of articles. These are my specs:

• When I visit the page I shouldn’t see any navigation.
• When I click the menu button, I want to see the navigation.
• When I click the menu button a second time, I stop seeing the navigation.

Also at this point I am going to introduce Jasmine to handle breaking the specs up. WebDriver.IO provides many examples including a Jasmine specific example, but this is where I ran in to some issues. I was getting the following error:

Started /Users/adrjohnston/Sites/webdriver-test/node_modules/webdriverio/node_modules/q/q.js:141
throw e;
Error: POST /session//url
Build info: version: '2.46.0', revision: '87c69e2', time: '2015–06–04 16:16:47'
System info: host: 'Adams-MBP', ip: '192.168.0.4', os.name: 'Mac OS X', os.arch: 'x86_64', os.version: '10.10.3', java.version: '1.8.0_45'
Driver info: driver.version: unknown
at new ErrorHandler.RuntimeError (/Users/adrjohnston/Sites/webdriver-test/node_modules/webdriverio/lib/utils/ErrorHandler.js:92:12)
at RequestHandler.<anonymous> (/Users/adrjohnston/Sites/webdriver-test/node_modules/webdriverio/lib/utils/RequestHandler.js:168:25)
at Request.self.callback (/Users/adrjohnston/Sites/webdriver-test/node_modules/webdriverio/node_modules/request/request.js:373:22)
at Request.emit (events.js:110:17)
at Request.<anonymous> (/Users/adrjohnston/Sites/webdriver-test/node_modules/webdriverio/node_modules/request/request.js:1318:14)
at Request.emit (events.js:129:20)
at IncomingMessage.<anonymous> (/Users/adrjohnston/Sites/webdriver-test/node_modules/webdriverio/node_modules/request/request.js:1266:12)
at IncomingMessage.emit (events.js:129:20)
at _stream_readable.js:908:16
at process._tickCallback (node.js:355:11)

So turns out that the documentation and the examples confused me somewhat and after a few of hours trying to figure things out I now have everything working.

I was following through the example and was trying to run it with WebDriver.IO’s test runner and when that failed, trying Jasmine’s runner but the error persisted. I think because I used wdio config it’s a way of using WebDriver.IO’s test runner which works a little bit differently and I found how to use the WebDriver.IO’s test runner in this example elsewhere. I prefer this approach so I am going to continue using:

$ wdio wdio.config.js

One thing to note. I currently don’t know what is setting the browser object. I cannot find a reference to it on the WebDriver.IO docs and so I am assuming it comes from Selenium or PhantomJS.

One last little issue I ran into. I was not calling Jasmine’s done callback after my specs and thus would cause a timeout exception.

Error: Timeout — Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.

I am not super familiar with Jasmine either so this is something worth reading into. So without further-ado here’s my spec with notes or just the basic version:

// ====== nav-menu.spec.js ======
describe('adamjohnston.co.uk', function () {
  beforeAll(function (done) {
    browser.url('/').call(done)
  })

  afterAll(function (done) {
    browser.end(done)
  })

  describe('when a user visits index', function () {
    it('should not have navigation visible', function (done) {
      browser
        .getCssProperty('nav[role=”navigation”]', 'opacity')
        .then(function (opacity) {
          expect(opacity.value).toBe(0)
        })
        .call(done)
    })
  })

  describe('when a user clicks the menu button', function () {
    it('should show the navigation', function (done) {
      browser
        .click('#jsNavBtn')
        .getCssProperty('nav[role=”navigation”]', 'opacity')
        .then(function (opacity) {
          expect(opacity.value).toBe(1)
        })
        .call(done)
    })

    it('should hide navigation if clicked again', function (done) {
      browser
        .click('#jsNavBtn')
        .getCssProperty('nav[role=”navigation”]', 'opacity')
        .then(function (opacity) {
          expect(opacity.value).toBe(0)
        })
        .call(done)
    })
  })
})

//  ======  terminal output  ======
$ wdio wdio.conf.js
․․․
3 passing (6.20s)

Summary

All in all not a bad couple of hours of work and a toolset that I definitely think I will invest more time in knowing. I think acceptance testing is very important and the combination of WebDriver.IO + Jasmine + PhantomJS seems promising.

I think my next steps will be to look into using it with Gulp (another tool WebDriver.IO supports) and try testing out a MeteorJS application (There are few WebDriver.IO packages on Atmosphere). Surely not long before I am JS acceptance testing machine!