DEV Community: Vince

Testing RxJS with Marbles

Vince — Mon, 13 Apr 2020 18:00:46 +0000

Foreword

As we learned in our first installment of the Learning RxJS series, RxJS is a reactive programming library. RxJS makes use of Observables, defined in the RxJS documentation as:

A representation of any set of values over any amount of time. This is the most basic building block of RxJS.
-source

So Observables are asynchronous, and represent a stream of values that are the result of an async operation. Anyone who has wrapped implementation code in an Angular project with a setTimeout() knows that testing that code in a fakeAsync() can cause some headaches, so you may be timid on putting the time into learning RxJS knowing you are adding more complex async code you'll have to test.

Why Marbles?

Marbles testing is the idea of breaking our Observables down into easy to read diagrams that show the passage of time for a specific Observable. They allow us to create rather easy to debug tests for complex, async, Observable based code. Lets look at the problem we are trying to solve.

Assume we have a simple piece of implementation code, a component that consumes some service that will be making an async call. Using the default HttpClient for Angular that call will return an Observable that we will need to consume in a component. That would look something like this:

export class MyService {

  constructor(private http: HttpClient) {}

  makeACall(): Observable<any> {
    return this.http.get('someUrl')
  }
}

export class MyComponent {
  value: any;

  constructor(private myService: MyService) {}

  getValue() {
    this.myService.makeACall().subscribe(val => this.value = val)
  }
}

In this simple example our MyComponent is making a call into MyService, who makes an HTTP request. However that service returns the Observable of that call, so our component subscribes and stores that value off. Testing this extremely simple service code would look something like this:

describe('MyService', () => {
  it('should return a get request to someUrl', () => {
    let value = undefined;
    httpSpy.get.and.returnValue(of('catseye'))

    myService.makeACall().subscribe(val => value = val);

    expect(value).toEqual('catseye')
  })
})

We can see that we are subscribing to the Observable returned by the service and storing that in a test scoped variable in order to test that value. We are loosely asserting that the value we push into the httpSpy is returned as an Observable from the service, and setting ourselves up for failure if this code were to grow more complex. We would need to do more and more work within the spec managing a fakeAsync timeline. Not to mention adding some common piped values to the HttpClient call such as a retry() or timeout() can easily make this code a pain to test and maintain.

Enter Marbles

A Marble Diagram is a simple string based diagram for representing the state of an Observable over time, they look something like this:

cold('-a--b-(c|)', { a: 'catseye', b: 'Bumblebee', c: 'Tiger' })

Don't worry too much about the symbols used or what cold means, we will take a look at those in a minute.

Marbles essentially allows us to write the future of an Observable, which we can then return from a spy to be consumed by our implementation code. This is extremely powerful, especially so, when our implementation is going to be modifying/pipe()-ing that Observable and operating on it in some way; more on that in a minute. Lets take a look at how we construct a marble diagram.

Note: When referring to marbles diagrams this artice is directly referring to the jasmine-marbles library recommended by the RxJS team. The official documentation can be found here

Hot and Cold

There are two types of marbles that we can create, hot() and cold()

hot() marbles create a hot observable that immediately begins emitting values upon creation
cold() marbles create a cold observable that only start emitting once they are consumed

Most of the time you will be creating cold() Observables within your tests.

Marbles Dictionary

- - The dash is used to represent one "frame" of time, generally 10ms passing. (this value may be different depending on the library being used and whether or not the marble is run within the testScheduler.run() callback)
# - The hash is used to represent an error being thrown by the Observable.
| - The pipe is used to represent the Observable completing.
() - The parentheses are used to represent events occuring on the same frame.
a - Any alphabetical letter represents an emitted value.
100ms - A number followed by ms represents a passage of time.
whitespace - Any and all whitespace is ignored in a marble diagram, and can be used to help visually align multiple diagrams.

There are also some subcription specific characters we can make use of:

^ - The caret represents a subscription start point.
! - The bang represents a subscription end point.

Emitting Values

Now that we know how to create a marble, lets look at how we emit values in a marble. Assume we need to emit a value of 'catseye' and then emit a specific error of the string 'Oops!' in order to test some logic.

cold('-a-#', { a: 'catseye' }, 'Oops!')

The first parameter is our diagram, here saying that after one frame of radio silence we emit some value a, then go quiet for another frame, finally on our fourth frame we throw an error.

The second parameter is an object containing our emitted values where the object's key is the character we used in the diagram, in our case a.

The third parameter is the value of the error, which we decided in our test case needed to be the string 'Oops!'. Lets look at another, more complex diagram example:

cold('-a--b 100ms (c|)', ...)

We are emitting value a on frame 2, value b on frame 5, then waiting 100ms. Then in a single frame our marble will emit value c and complete.

Writing Marbles Tests

Lets look at the service example from above, with a slight modification:

  makeACall(): Observable<any> {
    return this.http.get('someUrl').pipe(
      timeout(5000),
      retry(2),
      catchError(err => of(undefined))
    )
  }

Here we are making that same Get request as we were before, but we are telling the Observable to timeout if no result is recieved within 5 seconds, and retry that call twice, returning undefined if we still fail after retrying. This is a pretty common pattern for HttpRequests that can fail silently in an Angular application, and not that fun to test using the traditional subcribe() methodology shown above. Marbles are here to save the day!

describe('makeACall', () => {
  it('should return the value from someUrl', () => {
    httpSpy.get.and.returnValue(cold('-a', { a: 'catseye' }))

    const expected$ = cold('-e', { e: 'catseye' })

    expect(myService.makeACall()).toBeObservable(expected$)
  });

  it('should retry twice on error', () => {
    httpSpy.get.and.returnValues(
      cold('#'), 
      cold('#'), 
      cold('-a', { a: 'catseye' })
    )

    const expected$ = cold('---e', { e: 'catseye' })

    expect(myService.makeACall()).toBeObservable(expected$)
  })

  it('should have a timeout of 5 seconds and return undefined on error', () => {
    httpSpy.get.and.returnValue(cold('- 5000ms'))

    const expected$ = cold('- 15000ms e', { e: undefined })

    expect(myService.makeACall()).toBeObservable(expected$)
  })
})

All we need to do to make sure the source and expected Observables are working on the same timeline, is to line up the diagrams in terms of frames and timed waits.

A Note on Developer Experience

As we can see in the above examples we are creating an easily recreatable testing pattern. In order to understand the case all we need to do is look at the string pattern within the "source" returned by the httpSpy.

Marbles has allowed us to test more complex logic using the same pattern in all of our tests. Establishing patterns in your tests allows other developers to more easily write tests for new implementation code (and help you when you come back to that service you wrote 6 months ago).

Summary

Marbles testing gives us a rich shared language for testing Observables and creating easy to extend testing patterns. We can also test more complex RxJS code without getting lost in the weeds of how to test it. Overall we are able to write better tests that are easier to understand, improving the Developer Experience and allowing us to move faster without sacrificing code quality.

If you have any questions about using marbles in real practice, marbles in general, or the wider world of RxJS drop them in the comments below.

An Introduction to RxJs Observables

Vince — Wed, 12 Jun 2019 11:39:52 +0000

Understanding RxJs

Reactive Programming can be extremely difficult to understand. Here is a quick introduction to RxJs to hopefully get you started using reactive programming.

What Is An Observable?

An Observable is, in the simplest form, the result of an asynchronous operation. We can use them in place of Promises for a lot of asynchronous tasks. However an Observable allows for us to do complex logic on an async data stream with only a few lines of code.

The Basics

Before we get to the complex work we can do with Observables we should first understand the basics. There are a lot of helper methods to create Observables, for this example we will make use of interval(period: number). It creates an Observable that returns an incremented number every period milliseconds. Creating this observable is as simple as:

interval(1000);

This Observable will "emit", the term used for when an Observable produces a new value, the following 1 (one second) 2 (one second) 3....

Subscriptions

In order to get the emitted values from the above Observable we will need to "subscribe" to it.

const source = interval(1000);
source.subscribe(value => {
  console.log(value);
});

The above code will print out the emitted values as they are emitted from the Observable.

The Idea of the River

I find that when working with Observables it often helps to think of the "source" Observable as a river, with each emission being a boat that is floating down the river. By Subscribing to an Observable we are being given access to see the boats that are on the river. Next we will learn how to manipulate how and when those boats are perceived by someone watching the river.

The Pipe Operator

Here we are going to get into the more complex things we can do with Observables. We can achieve this using the pipe() function that exists on an Observable. Taking the source from above we can create a piped observable that only passes along even numbers.

const source = interval(1000);
source.pipe(
  filter(value => value % 2 === 0)
)
.subscribe(value => console.log(value))

This will print out 2 ... 4 ... 6 ... etc. We can see that the Observable has operators that can act upon the emitted values. Here we use filter(select: Function) to only accept values that are even. This is similar to the filter() function on arrays in JavaScript.

There are a load of pipeable operators that we can make use of.
Assume we have an Observable who's source is click events:

const source = fromEvent(document, 'click');

This will create an Observable who will emit every time there is a click event on the page.

Now say we need collect these click events into batches of 5 and then send them off to an arbitrary API for processing, which will then return a value from that processing which we need to print out, we will assume we have a service written that is ready to make the API call since that is out of the scope of this article. Here we can make use of the bufferCount(bufferSize: number, startBufferEvery: number = null) to do this.

const source = fromEvent(document, 'click');
source.pipe(bufferCount(5))

bufferCount(5) will collect 5 emissions from source and then emit them as an array. Now that we have our events batched we need to send them off to the API. Our service will return an Observable from its service call, so we need to take the value from our source and pass it to a function that makes a new Observable, and then return the new Observable. We can make use of the mergeMap() operator.

const source = fromEvent(document, 'click');
source.pipe(
  bufferCount(5),
  mergeMap(events => this.myAPIService.serviceCall(events))
)
.subscribe(processedEvents => console.log(processedEvents));

In a few lines of RxJs operators and functions we have created some, albeit odd, logic that could take many more lines to complete with Promises.

Conclusion

RxJs is an extremely powerful tool that can be extremely difficult to grasp, especially when working with large applications that retrieve data from multiple locations. I hope this article has helped shed some light on how Observables work. Feel free to drop any comments, questions, or concerns in the comments below.

Additional Resources

When I am working with Observables I often check learnrxjs.io. They have a list of Operators with examples and explanations of the operator. There is also a list of recipes showing the operators in action.

The official docs also contain useful information including marbles diagrams, which we will cover in the next article, and examples.

How I Vim

Vince — Fri, 24 May 2019 21:36:36 +0000

I Am Devloper

@iamdevloper

I've been using Vim for about 2 years now, mostly because I can't figure out how to exit it.

23:26 PM - 17 Feb 2014

13829 8673

Introduction

Vim jokes are as old as the editor itself. However I have been using Vim daily for years now, mostly for quick edits and writing commit messages. I figured I would share my setup and maybe someone else could find it helpful.

Ease of Use

The hardest thing for people to grasp when they first use Vim is the command system. This system can be extremely powerful, but for most use cases it just confuses new users on how to save the buffer they just wrote. Our first goal will be to abstract some of the more common commands to a hotkey combination.

First we need to create a .vimrc in our home directory touch .vimrc, since you may not be a vim user yet make the following changes with whatever editor you prefer.

We are going to be setting a "leader" which will be the start of all our hotkeys.

let mapleader = "`"

I prefer to use the

`

key since it is a bit out of the way and I am less likely to accidentally hit it, however you can set it to whatever you want.

Now we are going to create a command to write the current buffer:

noremap <leader>w :w<cr>

noremap is a mapping command that is not recursive, meaning we will not be chaining our new commands together. This can get a bit unwieldy for beginners and make it hard to debug. If you are comfortable with vim then feel free to use the recursive method map.

Once we tell vim that we are mapping something we use the <leader> tag to use that variable followed by w. So the keystrokes

` w

will write the current buffer via the command :w, executed by the <cr> carriage return. This one line is the equivalent of pressing esc, typing :w, and then hitting enter.

Now we can write some more common commands via noremap:

nnoremap <leader>a :wqall<cr>
nnoremap <leader>q :qall!<cr>

These two mappings will add

` a

to write quit all buffers that are open, and

` q

to quit all open buffers.

Now we can easily get out of vim!

Going Further

Now that we have some commands mapped out to easily write and quit vim we can start to make it feel more like home. Here is an excerpt from my own .vimrc:

" Turn on syntax highlightin
syntax on
" Turn on line numbers
set number
" Set the colorscheme to elflord
" See more colorschemes by entering command mode via esc then typing
" :colorscheme then pressing space and changing it via tab
colorscheme elflord

" Turn tabs into spaces and set them to be two spaces long
set expandtab
set tabstop=2
set softtabstop=2
set shiftwidth=2
set splitright

" highlight the current line of the buffer
set cursorline
" allow the mouse to be used to change cursor position
set mouse=a

" This block here executes the Vim Explorer on startup, opening the
" current directory tree in a small pane to the left
let g:netrw_banner = 0
let g:netrw_liststyle = 3
let g:netrw_browse_split = 4
let g:netrw_altv = 1
let g:netrw_winsize = 10
augroup ProjectDrawer
  autocmd!
  autocmd VimEnter * :Vexplore
augroup END

" `` should rotate split focus
noremap <leader><leader> <C-W><C-w>

Conclusion

I hope this has possibly helped you better work around vim, or piqued your interest to start customizing your own vim to your liking!

If you have any cool vim tips feel free to drop them in the comments, I'd love to up my vim game!

My First Open Source Project

Vince — Mon, 19 Nov 2018 13:28:11 +0000

Open Source can be daunting for new developers to get in to. Here are some tips that I have learned along the way while managing an, albeit small, active project.

Background

This project started around the time I was getting ready to graduate college, like most good projects it started because I was lazy. I had grown tired of constantly boiler-plating projects, so I made the MEVN Stack. A vanilla quick start template of my preferred technologies with some example code in there to help get others (and myself) going on a new full stack project.

The Beast of Open Source

Originally the project was made for myself and a few colleagues, however it started to get some traction from other developers on GitHub. Before I knew it the project was averaging 400-700 views every 2 weeks and had over 50 stars. With these new eyes on the project came contributions, and for me one of the scariest things.

People looking at my code.

When the project's first issue was opened my heart sank, I expected a programmer much better than myself to be tearing apart every aspect of my project. Turns out it was just a friend of mine calling out some redundant code that snuck in, a completely humbling experience. Since then the project has gained 2 more contributors, merged 2 pull requests, and closed 2 more issues. These are some things I learned along the way:

Mindset

It is easy to get a solid case of imposter syndrome when putting your work out for the world to see. Here are some tips for how to think when approaching Open Source:

Be humble.
When my first issue was calling out a simple redundant line of code I realized that 99% of the time if someone is opening an issue, they are commenting on your work in good faith. Issues are not where someone is going to call you out and tell you that you are not a real developer. The issue is more often than not a chance to improve the project, and yourself as a developer.
Keep an open mind.
If someone is reporting an issue that you cannot reproduce, attempt to gather more information. If they propose a code change, ask them to open a Pull Request. Review the changes they made, perhaps it does not affect the project on your environment, but will improve it on theirs.

Product

When most user's click on your project the only up front information they have is the name, and a README (hopefully). These tips pertain to the actual product, your code:

Write readable code.
When someone pops open the source code of your project they should be able to read and understand what it is doing. Not only do I mean that your code should be formatted properly, it should also be understood. Give variables and functions meaningful names, follow (or at least loosely follow) standards that people are expecting to see. Do your best to remove the mystery around your source code, this will make it easier for others to use and help them over the hurdle of starting to contribute.
Keep it simple.
This is applicable in most cases. If there is no benefit to using the super convoluted function you just thought up, then don't. Every point in your code that makes it harder for another dev to "compile" in their head, is another point you could lose a potential contributor. In cases where simplicity is unattainable, leave a comment in your code.

Self-Care

When people are using your code you may feel obligated to carve time out of your day to fix problems they are having, or improving their experience. You should do these things, but not at the expense of your own health. These are some things I learned about putting yourself first:

Don't overcommit.
When working in Open Source, people will ask for improvement, help, and bug fixes. It is easy to get in the mindset of "Someone asked for X, I have to drop everything and do it". However you come first, if you do not have the time due to other commitments, or are starting to burn out a bit; ask the reporter if they would like to submit the fix. This helps you keep a balance, helps the project remain maintained, and helps someone else contribute.
Find a balance.
I work 40+ hours a week along with a long commute and travel. Finding time to work on projects can be a bit difficult. The best I have found is taking a chunk of time during a vacation or long weekend to get some tasks done. This works well for me, I get to hit a groove and check off a bunch of work without it encroaching too much into the rest of my time off. Find what works best for you and stick to it, if someone is asking you to do some work and not respecting your timetables then they are not coming to you in good faith.

I hope these tips I picked up in the past year of working in Open Source is helpful to developers looking to get their foot in the door and seasoned contributors alike. If you have any more helpful hints to contributing feel free to drop them in the comments below!

DEV Community: Vince

Testing RxJS with Marbles

Foreword

Why Marbles?

Enter Marbles

Hot and Cold

Marbles Dictionary

Emitting Values

Writing Marbles Tests

A Note on Developer Experience

Summary

Further Reading

An Introduction to RxJs Observables

Understanding RxJs

What Is An Observable?

The Basics

Subscriptions

The Idea of the River

The Pipe Operator

Conclusion

Additional Resources

How I Vim

Introduction

Ease of Use

Going Further

Conclusion

My First Open Source Project

Background

The Beast of Open Source

Mindset

Product

Self-Care