Balint Erdi's tech blog

The Rock & Roll with Ember band - Michal Bryxí

2024-11-15T10:16:00+00:00

The "Rock & Roll with Ember band" interview series introduces readers of the similarly titled book. They tell us about how they got acquainted with the framework, how they learned it, what they use it for, and share a few more details about the non-tech related side of their lives. I hope you enjoy reading them as much as I did.

Could you introduce yourself in a few sentences?

Hi, I'm Michal Bryxí, or Míša. You might know me from EmberJS Discord, conferences or just the internet space. I'm quite a keen advocate of good UX, not blaming users for the faults of the IT industry and spending my time in any other way than at the computer.

Which part of the world are you from?

Originally I come from Czechia, but I've been living in UK for ~7 years and now I'm based in Interlaken - Switzerland.

When and how did your Ember journey begin? How did you learn about the framework?

Because I used Puppet (configuration management software) in my previous company, I thought it would be cool to start working for Puppet (the company). After I started they told me that they actually need me on some frontend project and I will be working with something called Ember.

Right after I started, the company shipped me to Portland to attend EmberConf (2016). On the long way in the plane I was hacking away on what would become my biggest project using Ruby on Rails. But since it was a very long flight I thought I should give Ember a try to see if I can use it for fun projects & learn something for work.

It was a perfect match and I'm happy to report that said app is still running without any major rewrite ever since.

How did reading the Rock & Roll with Ember book help you? Can you recall something that you learned from it?

The basics. I'm not very patient person and I tend to jump from thing to thing when building something, often times missing a lot of crucial details in doing so. Rock & Roll with Ember gives the end to end story and shows all the little pieces that come into play when building EmberJS applications.

What Ember feature/RFC/etc. are you most excited about?

This changes all the time to be honest. But I'm super happy that ember-data is getting a big overhaul as I consider it the most important part for all my projects. Dropping custom build story and plugging into the vite world sounds super promising. And for the future I'm curious about dropping controllers and overhaul of the routing system.

Is there something you’d like to see covered or explained in more detail in the book?

Short answer: Ember Data. I don't consider building an UI that displays stuff and reacts to user inputs that hard. As you can (mostly) dictate all the bits and pieces. But state mutation, persistence, updates ... that's something where a lot of things can go sideways.

Are there any (side-)projects that you’ve built in Ember? What is it (are they) about?

E2E Beauty Salon management solution (hello Phorest :)). I've been working on it on and off for over a decade and it's still going strong.
Private location tracking visualisation tool. This was built in ~two weekends.
POC frontend replacement for live winds tracking. I hope to replace the original Angular app; this also probably took me ~2 weekends.

Were there any challenges or stumbling blocks while you were building your app(s)?

The usual:

Documentation
- Sometimes things are missing
- Sometimes links within the docs are broken
- Sometimes search in the docs is not working
- Sometimes you stumble upon DenverCoder9 comment
Addons
- There are quite a few that used to work, but are deteoriating now
- Some addons have quite a list of PRs from folks, but nobody merges them for year(s)
NullVoxPopulli is on vacation
- Then, I think, we all feel like our productivity goes down

What do you like to do in your free time?

Trail running & paragliding

If people would like to follow you (or your project), where can they do so?

Right now I'm probably most active on my Mastodon

Is there something else you’d like to say?

I love folks from around EmberJS community. The love, patience, thoughtfulness and general community vibe. You are the best!

If you've read the book, and would like to give a similar interview, please drop me a line at rarwe-book@balinterdi.com.

If you'd like to join the Rock & Roll with Ember band, check out the book of the same name to learn Ember (and be part of a band).

Testing async DOM functions in Ember.js - a custom waiter alternative

2024-01-18T09:18:00+00:00

In my last blog post, we wrote a custom test waiter to reliably test a component that relied on a DOM callback that wasn't integrated into Ember's testing framework.

In the end, we saw that the test also passed without the test waiter when we added an extra await settled() after the component was rendered.

This seemed counter-intuitive, and Ember even called us out on it via a lint error since await render() already calls settled internally.

This post discovers why this passes and offers an alternative to implementing a custom test waiter.

To harness the collective mind of the Ember ecosystem, I asked the question on Discuss. The responses confirmed my suspicion about why it passes, and I also received a few great ideas about alternatives.

Buying just a little bit of time

The test looks like this:

 1module('Integration | Component | avatar', function (hooks) {
 2  setupRenderingTest(hooks);
 3
 4  test('It falls back to initials when the image cannot be loaded', async function (assert) {
 5    await render(
 6      hbs`<Avatar @name="Marquis de Carabas" @url="/images/non-existent.webp" />`,
 7    );
 8    await settled();
 9    assert.dom('.initials').hasText('MC');
10  });
11});

The extra settled call takes very little time, but seems enough for the DOM function to complete in almost all cases (I re-ran the test about 50 times, and it passed every time).

So this fixes the test by a happy incident: Ember doesn't wait for the callback to complete, but the few milliseconds added by the extra settled is just enough for this, so the assertion finds the component in the expected state.

Short of implementing the waiter, can we do better?

Wait for it

One of the great things about Ember is that it takes testing seriously and thus allows us great tools to test our apps. Unsurprisingly, it has a test helper for this case called waitFor.

The docstring of waitFor tells a great deal about what we can use it for:

Used to wait for a particular selector to appear in the DOM. Due to the fact that it does not wait for general settledness, this is quite useful for testing interim DOM states (e.g. loading states, pending promises, etc).

Without the waiter, general settledness doesn't help us, so waitFor works great for our use case: we want to wait for the initials to appear so that we know that our fallback worked correctly:

 1module('Integration | Component | avatar', function (hooks) {
 2  setupRenderingTest(hooks);
 3
 4  test('It falls back to initials when the image cannot be loaded', async function (assert) {
 5    await render(
 6      hbs`<Avatar @name="Marquis de Carabas" @url="/images/non-existent.webp" />`,
 7    );
 8    await waitFor('.initials');
 9    assert.dom('.initials').hasText('MC');
10  });

This works great! The default timeout, 1000ms, is more than enough for the callback passed to onError to run and render the initials, so this makes the test pass (you can pass another timeout value if you specify a timeout parameter).

(To add another tool to your testing toolbelt: waitFor calls another waiter function, waitUntil, which is even more potent as you can wait for more things than the appearance of a selected DOM element)

Custom waiter vs. waitFor

It's important to note that the mechanism by which the extra settled() and waitFor() make the test pass is similar.

Although waitFor is specific about what it wants to see in the DOM, it doesn't guarantee that our implementation works: if it takes more than 1000 msecs for our onError callback plus the re-render to run, it will fail.

The custom waiter solution is more reliable: as Ember's testing framework doesn't execute the assertion before the waiter has finished, it guarantees there will be no false negatives (the test saying the implementation doesn't work when it does).

So, which one should you pick?

You probably won't like the answer, but I have to say: "it depends." :)

I like the actual guarantee that the test waiter brings, I think it's the "real", the most reliable solution.

On the other hand, it's certainly more ceremony than waitFor, and you have to add a non-trivial amount of code to the component "just" to test it (see the "Adding code to make something testable" section in the last post).

And if you don't have control over the code you test, you can't add a waiter to it, so your only option is waitFor.

waitFor is also great for testing interim DOM state (as the code comment says), like verifying that a toast message is shown. In those cases, you can't use a custom waiter because you don't want to wait for everything to settle.

So as not to avoid deciding on this one, I'd add a custom waiter, but I wouldn't hesitate for a moment to approve a PR that uses a waitFor.

Thanks to Dan and Boris for replying to my Discuss blog post. It served as the content for this blog post.

Testing async DOM functions in Ember.js

2023-12-18T10:41:00+00:00

"Just use the platform" - they say, referring to not reinventing the wheel for a browser feature in our favorite JavaScript framework if the browser already provides it.

And they are right! If a browser spec is implemented by the browsers we care about, it makes perfect sense to use it. We have to consider a few other things, though, one of which is whether the feature can be properly tested.

In this post, we'll see a specific example of using a browser feature, and making it testable in Ember.js.

Showing an avatar – or the initials

An avatar component is a recurring element in web applications. We want to show a user's face and name together, in a specific layout (most often, next to each other). Such a component should take a name and a URL to the image:

1<Avatar @name="Marquis de Carabas" @url="/photos/carabas.png" />

Simple enough, but what happens if the image can't be loaded? We could rely on the browser showing the "broken image" symbol but I think in this case we can do better than just "using the platform": we can show the user's initials instead:

Right, but how do we know that the image cannot be loaded? Turns out there is an onError callback on img tags which is only called in this exact case. Based on that, the implmentation of our Avatar component can look something like this:

 1// avatar.js
 2export default class AvatarComponent extends Component {
 3  @tracked isShowingInitials = false;
 4
 5  get initials() {
 6    const [first, ...rest] = this.args.name.split(/\s+/);
 7    const last = rest.pop();
 8    return [first, last].map((name) => name[0]).join('');
 9  }
10
11  @action
12  showInitials() {
13    this.isShowingInitials = true;
14  }
15}

The onError callback can be hooked up to the showInitials action. We only want to show the initials if the image is not available:

{{!-- avatar.hbs --}} 
<div class="avatar">
  {{#if this.isShowingInitials}}
    <div class="initials">{{this.initials}}</div>
  {{else}}
    <img
      src={{@url}}
      onError={{this.showInitials}}
      alt={{concat @name "'s avatar"}}
    />
  {{/if}}
  <div class="name">{{@name}}</div>
</div>

Everything looks good but we want to add a test to make sure this stellar feature doesn't break in the future.

With the hopefulness of a junior developer, we write a simple test for the failure case. We already saw it works in the real app, so it should be as simple as centering an element vertically in a container:

 1// avatar-test.js
 2module('Integration | Component | Avatar', function (hooks) {
 3  setupRenderingTest(hooks);
 4
 5  test('It falls back to initials when the image cannot be loaded', async function (assert) {
 6    await render(
 7      hbs`<Avatar @name="Marquis de Carabas" @url="/images/non-existent.webp" />`,
 8    );
 9
10    assert.dom('.initials').hasText('MC');
11  });
12});

Reality beckons: all is not so simple in the world of software, and our test fails.

However, if we insert an await this.pauseTest() after the component is rendered, we see that the initials are correctly shown. Furthermore, if we release the breaks by typing resumeTest() on the console, the test passes!

What is this sorcery?

What do test helpers wait for?

One of the most educational moments in my Ember.js learning journey was to peek into what Ember's test helpers wait for before moving on to the next test line to execute. The foundation of those helpers is called wait and most test helpers return a call to that function. It tells us what the framework waits for before moving on. Go take a look yourself, it's a very short file and very well written.

You'll see that test helpers will wait for the router to finish transitioning, pending ajax requests, scheduled timers and the runloop, and something called waiters.

None of these cover the case of the onError callback so the assert.dom assertion runs before the initials were rendered and we get a failing test.

The solution (or at least one solution) for this is to integrate the onError DOM element callback into Ember's testing mechanism by defining a custom test waiter.

Adding a custom test waiter

If we define a waiter for our component, Ember's testing mechanism will wait for it to complete before moving on which will make the test pass.

We start by creating the waiter in the module's scope:

 1// avatar.js
 2import Component from '@glimmer/component';
 3import { action } from '@ember/object';
 4import { tracked } from '@glimmer/tracking';
 5import { buildWaiter } from '@ember/test-waiters';
 6
 7const waiter = buildWaiter('avatar');
 8
 9export default class AvatarComponent extends Component {
10  // (...)
11}

The waiter has two functions: beginAsync should be called to get a token and start the waiting:

 1// avatar.js
 2export default class AvatarComponent extends Component {
 3  @tracked isShowingInitials = false;
 4
 5  constructor() {
 6    super(...arguments);
 7    this.waiterToken = waiter.beginAsync();
 8  }
 9  // (...)
10}

, and endAsync should be called when the waiter completes, passing it the token we received earlier:

 1// avatar.js
 2export default class AvatarComponent extends Component {
 3  // (...)
 4  @action
 5  showInitials() {
 6    this.isShowingInitials = true;
 7    waiter.endAsync(this.waiterToken);
 8  }
 9}

Once we do that, the waiter will now make Ember's testing framework wait it finishes, and only then move on to check the assertion. Our test is now reliably green.

Covering the happy path

We might think it's time to call it a day and have some fun but then we'd miss the important non-corner case. What if the image is available at the provided URL and can be loaded? Well, let's write a test for it:

 1// avatar-test.js
 2module('Integration | Component | Avatar', function (hooks) {
 3  setupRenderingTest(hooks);
 4
 5  // (...)
 6  test('It renders the image when the image can be loaded', async function (assert) {
 7    await render(
 8      hbs`<Avatar @name="Chelsea Hagon" @url="/images/chelsea.avif" />`,
 9    );
10
11    assert.dom('img').exists('The image is displayed');
12    assert.dom('.initials').doesNotExist();
13  });
14});

Assuming that the image is available at /images/chelsea.avif (it will be if we copy it to the /public/images folder in our app), this test should pass. Instead, it hangs – it never runs to completion.

We forgot (or maybe you didn't ;) ) that endAsync is only called from showInitials when the image cannot be loaded. When it can be, the waiter just waits forever and the test never moves to the next line, the assertion.

The img element also has an onLoad callback which is triggered when the image has been loaded, so we can use that for calling endAsync on the happy path:

<div class="avatar">
  {{#if this.isShowingInitials}}
    <div class="initials">{{this.initials}}</div>
  {{else}}
    <img
      src={{@url}}
      onLoad={{this.completeWaiter}}
      onError={{this.showInitials}}
      alt={{concat @name "'s avatar"}}
    />
  {{/if}}
  <div class="name">{{@name}}</div>
</div>

The completeWaiter action is only there to make sure we complete the async operation:

1// avatar.js
2export default class AvatarComponent extends Component {
3  // (...)
4  @action
5  completeWaiter() {
6    waiter.endAsync(this.waiterToken);
7  }
8}

Our second test now also passes.

There is a small change which I think is worth doing – moving the image used for testing in a folder that clearly shows its purpose. One called testing is clear enough :) Otherwise, someone might delete the image when they see it's not used anywhere in the app. If we do that, we have to update the image path in the test:

 1// avatar-test.js
 2module('Integration | Component | Avatar', function (hooks) {
 3  setupRenderingTest(hooks);
 4
 5  // (...)
 6  test('It renders the image when the image can be loaded', async function (assert) {
 7    await render(
 8      hbs`<Avatar @name="Chelsea Hagon" @url="/images/testing/chelsea.avif" />`,
 9    );
10
11    assert.dom('img').exists('The image is displayed');
12    assert.dom('.initials').doesNotExist();
13  });
14});

Adding code to make something testable

At this point you could justifiedly point out that we're only adding code, all the code related to the custom waiter, to be able to test our avatar component. Isn't it wrong to make the code more complex for the purpose of testability? I think the value that having our component be tested and guarded against regression makes up for the fact that the code is slightly more complex. That said, it'd be great not having to add any code to be able to do that. Can we?

Does `settled` settle it?

As I was going through the code for a second time for this post, I pulled out the joker that on occasions helps tests pass that otherwise would have failed for the same reason as explained in this post: when Ember's testing framework doesn't wait for an async event to complete before executing the next testing instruction. Lo and behold: it did work this time, too!

Inserting a call to settled() (imported from @ember/test-helpers) makes the test pass reliably:

 1module('Integration | Component | avatar', function (hooks) {
 2  setupRenderingTest(hooks);
 3  test('It falls back to initials when the image cannot be loaded', async function (assert) {
 4    await render(
 5      hbs`<Avatar @name="Marquis de Carabas" @url="/images/non-existent.webp" />`,
 6    );
 7    await settled();
 8    assert.dom('.initials').hasText('MC');
 9  });
10});

But... it shouldn't. settled doesn't add anything that should make Ember wait for the callback to complete, so the things I explained in the "What do test helpers wait for?" section still hold. Actually, we even get a squiggly (a lint error) in our editor because our code now violates the ember/no-settled-after-test-helper rule:

1> Do not call `settled()` right after a test helper that already calls it internally.

And indeed, the render call does call settled under the hood.

So I'm not sure why it works and it seems like it shouldn't and maybe I just got lucky all the times I ran the test?

I'll try to find out but in the meantime, I suggest adding a test waiter. It's a very useful tool in one's Ember.js arsenal and you can use it in several contexts to let Ember's testing know about an added async operation.

Using simple functions as helpers in Ember.js

2023-11-13T11:00:00+00:00

Possibly one of the least known and most useful things in Ember is the ability to use simple functions as template helpers which was introduced in Ember 4.5.

Before, if you wanted to use a function in the template, you needed to create a helper after which you could use it in all of your templates. If you defined a format-currency helper, you could call it as {{format-currency value}} from everywhere.

Handy, but I can think of two downsides. First, you need a special kind of function, a helper which is an Emberism. Second, and I think this is the bigger downside, it's hard to say where a certain helper comes from. It could've been created by one of the developers of the app in which case you'd find the helper in app/helpers. But it also could be in any of your dependencies and good luck searching through all of them.

Let's see an example of the modern, more explicit way.

A simple currency converter

Let's say we want to display currencies, select a base currency, and display the value of each in the base currency.

We start by just having the conversion rates (compared to the EUR), and listing the currencies and a dropdown to change the base currency:

import Component from '@glimmer/component';

export default class CurrencyConverterComponent extends Component {
  currencies = {
    EUR: 1,
    USD: 1.06,
    GBP: 0.87,
    CHF: 0.95,
    BTC: 0.000036,
  };
}

<div class="currencies-container">
  <h1 class="header">
    <label for="selected-currency">Currencies</label>
    <select
      id="selected-currency"
      name="selected-currency"
      class="currency-dropdown"
    >
    {{#each-in this.currencies as |symbol|}}
      <option>{{symbol}}</option>
    {{/each-in}}
    </select>
  </h1>

  <ul class="currencies">
    {{#each-in this.currencies as |symbol rate|}}
      <li class="currency-price">
        {{symbol}}
        <span>{{rate}}</span>
      </li>
    {{/each-in}}
  </ul>
</div>

Simple enough, but we're missing the ability to change the base currency, so let's make some changes.

Allowing to change the base currency

export default class CurrencyConverterComponent extends Component {
  eurRates = {
    EUR: 1,
    USD: 1.06,
    GBP: 0.87,
    CHF: 0.95,
    BTC: 0.000036,
  };

  @tracked baseCurrency = 'EUR';

  get currencyRates() {
    return Object.entries(this.eurRates).map(([currency, rate]) => {
      return {
        symbol: currency,
        rate: rate / this.eurRates[this.baseCurrency],
      };
    });
  }

  @action
  updateBaseCurrency(event) {
    this.baseCurrency = event.target.value;
  }
}

Before we'd assumed the base currency would always be the EUR but if it can be changed, we need to show the rates compared to the base currency which is what currencyRates does.

The template also needs to change, though only slightly:

<div class="currencies-container">
  <h1 class="header">
    <label for="selected-currency">Currencies</label>
    <select
      id="selected-currency"
      name="selected-currency"
      class="currency-dropdown"
      {{on "change" this.updateBaseCurrency}}
    >
    {{#each this.currencyRates as |currency|}}
      <option>{{currency.symbol}}</option>
    {{/each}}
    </select>
  </h1>

  <ul class="currencies">
    {{#each this.currencyRates as |currency|}}
      <li class="currency-price">
        {{currency.symbol}}
        <span>{{currency.rate}}</span>
      </li>
    {{/each}}
  </ul>
</div>

We want to bind the selected option of the dropdown to the base currency. The classic way to do this would be using the eq helper which you can either use from ember-truth-helpers or write yourself.

However, there is a more descriptive way (and this is a blog post about using simple functions as helpers, so let me have it my way), by writing a local helper function:

export default class CurrencyConverterComponent extends Component {
  eurRates = {
    EUR: 1,
    USD: 1.06,
    GBP: 0.87,
    CHF: 0.95,
    BTC: 0.000036,
  };

  @tracked baseCurrency = 'EUR';

  isBaseCurrency = (currency) => {
   return currency === this.baseCurrency;
  };

  // (...)
}

<select
  id="selected-currency"
  name="selected-currency"
  class="currency-dropdown"
  {{on "change" this.updateBaseCurrency}}
>
  {{#each this.currencyRates as |currency|}}
    <option selected={{this.isBaseCurrency currency.symbol}}>
      {{currency.symbol}}
    </option>
  {{/each}}
</select>

We use a local function as a helper so we need to use the this prefix, just as when rendering a property or calling an action.

Formatting currencies (well, numbers)

The currencies I listed are all close to each other (with one exception) in value so it's not trivial to see but when we switch the base currency to BTC, we can see that bigger values are somewhat hard to read:

We should add a formatter (helper) function to present the numbers is a nicer way:

1export default class CurrencyConverterComponent extends Component {
2
3  formatCurrency = (value) => {
4    // Format the value to two decimals and separate thousands by commas
5    return value.toFixed(2).replace(/\d(?=(?:\d{3})+\.)/g, '$&,');
6  };
7  // (...)
8}

There is some regex magic to add the commas between the thousands but that's not our focus today.

We now have a function we can call from the template:

{{#each this.currencyRates as |currency|}}
  <li class="currency-price">
    {{currency.symbol}}
    <span>{{this.formatCurrency currency.rate}}</span>
  </li>
{{/each}}

Note we call the formatCurrency method with this as it's defined on the component – it's not a global helper.

Extracting the function to be reused

You might justifiedly ask: "all right, but what if I need the formatCurrency helper in other places of the app, too? Before, I could just define it once as a helper and then use it everywhere." Good point, you don't want to redefine the formatter every time you need it – but you don't have to.

The helper is just a regular function, so you can define it in a module and then import it each time you need it:

1// app/helpers/format-currency.js
2export function formatCurrency(value) {
3  return value.toFixed(2).replace(/\d(?=(?:\d{3})+\.)/g, '$&,');
4}

1import { formatCurrency } from 'currencies/helpers/currency';
2
3export default class CurrencyConverterComponent extends Component {
4  formatCurrency = formatCurrency;
5}

Assigning the imported function to a property on the component is needed because you can't simply use formatCurrency in the template.

At least not in current Ember, Octane. With single-file components, in Polaris, you can: give it a whirl using the ember-template-imports add-on.

Is there still a place for "classic" template helpers?

Before we could use simple functions as helpers, there were two types of Ember helpers: functional and class-based ones.

Functional helpers

Above I showed how to use a simple function in a helper/util module by importing it, assigning it to a component property and calling it from a template.

It's true this is more ceremony than defining a special, global helper but I think it's worth it because it is explicit, and it's just JavaScript. With the exception of needing to assign the function to a component property, you don't have to do anything about Ember to use this technique.

So, unless the helper is already defined in the project (via libraries like ember-truth-helpers, ember-composable-helpers, etc.), I see no reason to create and use global helpers.

Class-based helpers

We need a class-based global helper when we need some state to create the output. Some property that we can't, or don't want to pass in to the helper every time.

A translation helper, like t in ember-intl is a good example. You don't want to pass in the current locale needed for the translation every time you call the helper – the class implementing the helper can store it instead.

It's also a good example because under the hood, the helper makes use of a service, so we can do the same.

Let's see how that would be done on the previous example.

We define a session service that keeps track of the currently selected base currency throughout the application. All operations related to the management of this base currency will live on the service:

 1import Service from '@ember/service';
 2import { action } from '@ember/object';
 3import { tracked } from '@glimmer/tracking';
 4
 5export default class SessionService extends Service {
 6  @tracked currency = 'EUR';
 7
 8  formatCurrency(value) {
 9    const formatted = value.toFixed(2).replace(/\d(?=(?:\d{3})+\.)/g, '$&,');
10    return `${this.currency} ${formatted}`;
11  }
12
13  @action
14  setCurrency(currency) {
15    this.currency = currency;
16  }
17}

The formatCurrency helper can now use the base currency (this.currency) which is defined on the service itself.

Because previously this responsibility was implemented in the component, we now need to pass the "value + updater" pair into the component:

1<CurrencyConverter
2  @baseCurrency={{get (service "session") "currency"}}
3  @onChange={{get (service "session") "setCurrency"}}
4/>

(I used the very handy ember-service-helper add-on so as not to create a controller for the service injection.)

The component class needs to change to not manage the base currency itself:

import Component from '@glimmer/component';
import { action } from '@ember/object';
import { service } from '@ember/service';

export default class CurrencyConverterComponent extends Component {
  @service session;

  eurRates = {
    EUR: 1,
    USD: 1.06,
    GBP: 0.87,
    CHF: 0.95,
    BTC: 0.000036,
  };

  isBaseCurrency = (currency) => {
    return currency === this.args.baseCurrency;
  };

  formatCurrency = (value) => {
    return this.session.formatCurrency(value);
  };

  get currencyRates() {
    return Object.entries(this.eurRates).map(([currency, rate]) => {
      return {
        symbol: currency,
        rate: rate / this.eurRates[this.args.baseCurrency],
      };
    });
  }

  @action
  updateBaseCurrency(event) {
    this.args.onChange(event.target.value);
  }
}

(The example is contrived because there is no place for the base currency to be included in each value. A better example would be an app for finding flight tickets where the user can set a currency preference and wants to see all prices in that currency.)

Why do we still need the formatCurrency method on the component? Couldn't we use this.session.formatCurrency directly in the template?

No, we couldn't: this.session.formatCurrency is a function and its context is not bound to the component instance so the this in the service would be undefined during the call.

A note on currency formatting

One of my readers, Johan Roed, points out that we could use Intl.NumberFormat to do the currency formatting. I prefer this solution to using a regex indeed, as it's simpler and also adjusts to user preferences. Thanks, Johan!

Which one to use?

The decision to use a global, class-based Ember helper or a method on a service and a thin wrapper around it is harder to make than in the functional helper case. I'm still learning toward the latter because of its explicitness and the fact that you don't have to learn about a special Ember thing.

When single-file components become the norm in Polaris, we'll have to import all the helpers anyway so the decision will be an easy one to make :)

Uploading images to S3 in Ember.js – Part 4: Testing

2022-05-20T09:05:00+00:00

We concluded Part 3 of this series by having added the ability to upload an image to a band both when creating and when editing one.

In this post, we'll add a couple of tests to safeguard those user scenarios.

Existing test for creating a band

In the Rock & Roll with Ember book we'd written a test to verify creating a band works fine. It looks something like this:

 1// tests/acceptance/bands-test.js
 2test('Create a band', async function (assert) {
 3  this.server.create('band', { name: 'Royal Blood' });
 4
 5  await visit('/');
 6  await createBand('Red Hot Chili Peppers');
 7  await waitFor('[data-test-rr="no-songs-text"]');
 8
 9  assert
10    .dom('[data-test-rr="band-list-item"]')
11    .exists({ count: 2 }, 'A new band link is rendered');
12  assert
13    .dom('[data-test-rr="band-list-item"]:last-child')
14    .hasText('Red Hot Chili Peppers', 'The new band link is rendered as the last item');
15});

The createBand is a custom test helper that reduces boilerplate without reducing the clarity of what's going on in the test setup (or so I hope):

1export async function createBand(name) {
2  await click('[data-test-rr="new-band-button"]');
3  await fillIn('[data-test-rr="new-band-name"]', name);
4  return click('[data-test-rr="save-band-button"]');
5}

We need to extend the test to allow uploading an image. More precisely, we want to end up with two test cases: one where an image is uploaded and one where it's not.

A bug revealed

In my experience, even just thinking about what to test is a great way to reduce the number of bugs in your code. It forces you to consider scenarios you might have forgot about when writing the implementation (which I guess is one of the reasons test-driven development is valuable).

In our case, I'd made a colossal error – I assumed that an image was always uploaded when creating a new band.

Look at the code:

// app/components/band-form.js
export default class BandFormComponent extends Component {
  // (...)
  @action
  async save(event) {
    event.preventDefault();
    let response = await fetch('/presign-aws-request', {
      method: 'POST',
    });
    let { url, url_fields: urlFields } = await response.json();
    let bandProperties = {
      name: this.name,
    };

    let formData = new FormData();
    for (let field in urlFields) {
      formData.append(field, urlFields[field]);
    }
    formData.append('file', this.imageToUpload);

    let imageUploadResponse = await fetch(url, {
      method: 'POST',
      body: formData,
    });

    if (imageUploadResponse.ok) {
      bandProperties['image-url'] = imageUploadResponse.headers.get('Location');
      this.imageToUpload = null;
    }
    return await this.args.onSave(bandProperties);
  }
}

Nothing checks for the presence of this.imageToUpload and the very first line posts to the back-end for a pre-signed URL. This is not needed if the user hasn't uploaded the image, just as all the following code is not.

So the code should be modified as follows:

// app/components/band-form.js
export default class BandFormComponent extends Component {
  // (...)
  @action
  async save(event) {
    event.preventDefault();
    let bandProperties = {
      name: this.name,
    };

    if (this.imageToUpload) {
      let response = await fetch(`${ENV.apiHost}/presign-aws-request`, {
        method: 'POST',
      });
      let { url, url_fields: urlFields } = await response.json();

      let formData = new FormData();
      for (let field in urlFields) {
        formData.append(field, urlFields[field]);
      }
      formData.append('file', this.imageToUpload);

      let imageUploadResponse = await fetch(url, {
        method: 'POST',
        body: formData,
      });

      if (imageUploadResponse.ok) {
        bandProperties['image-url'] =
          imageUploadResponse.headers.get('Location');
        this.imageToUpload = null;
      }
    }

    return await this.args.onSave(bandProperties);
  }
}

I'm following the path I trod when adding the tests - I realized the above bug before even starting to write the tests. As the next step, let's write the tests as I did.

Writing new tests

We want at least two test scenarios for band creation: one where an image is uploaded and one where it's not. If you take a look at the existing test, it makes use of a custom test helper called createBand which hides the details about the needed user actions:

1// tests/helpers/custom-helpers.js
2import { click, fillIn } from '@ember/test-helpers';
3
4export async function createBand(name) {
5  await click('[data-test-rr="new-band-button"]');
6  await fillIn('[data-test-rr="new-band-name"]', name);
7  return click('[data-test-rr="save-band-button"]');
8}

We can extend this helper to take an optional image argument and then select that file when it's passed.

Selecting a file is done by triggering a change event on the file upload input, passing along the selected files:

 1// tests/helpers/custom-helpers.js
 2import { click, fillIn, triggerEvent } from '@ember/test-helpers';
 3
 4export async function createBand({ name, image }) {
 5  await click('[data-test-rr="new-band-button"]');
 6  await fillIn('[data-test-rr="new-band-name"]', name);
 7  if (image) {
 8    await triggerEvent('[name="file-upload"]', 'change', { files: [image] });
 9  }
10  return click('[data-test-rr="save-band-button"]');
11}

In the process, we also switched to named arguments.

Let's now write the test scenarios we've imagined.

Test case for creating a band with an image

// tests/acceptance/bands-test.js
// (...)
import { createBand } from 'rarwe/tests/helpers/custom-helpers';

module('Acceptance | bands', function (hooks) {
  // (...)
  test('Create a band — with image', async function (assert) {
    this.server.create('band', { name: 'Royal Blood' });

    await visit('/');
    let image = new File([], 'red-hot-chilli-peppers.jpg', {
      type: 'image/jpeg',
    });
    await createBand({
      name: 'Red Hot Chili Peppers',
      image,
    });
    await waitFor('[data-test-rr="band-image"]');

    assert.dom('[data-test-rr="band-image"]').exists('The band image is shown');
    assert
      .dom('[data-test-rr="band-list-item"]')
      .exists({ count: 2 }, 'A new band link is rendered');
    assert
      .dom('[data-test-rr="band-list-item"]:last-child')
      .hasText(
        'Red Hot Chili Peppers',
        'The new band link is rendered as the last item'
      );
    assert
      .dom('[data-test-rr="details-nav-item"] > .active')
      .exists('The Details tab is active');
  });
});

A File object is what's passed "in the real app" so we create one manually in the tests. The reason we don't have to pass its contents (see the empty array passed as the first argument to the constructor) is that the endpoints are mocked out in the test anyways, so we'll pretend we got the right thing.

We add a waitFor to make sure the transition to the Details page of the newly created band is complete.

The test will fail as we haven't added Mirage handlers for the presign back-end endpoint and the AWS bucket URL. Let's open up mirage/config.js and add them.

// mirage/config.js
import { Response } from 'miragejs';

const s3BucketUrl = 'https://rarwe-dev.s3.eu-west-1.amazonaws.com';
const bucketName = 'rarwe-dev';
const imageId = '69c4abfc-e900-4ec7-9263-c2506bdd4c19';
const keyInBucket = `image-uploads/${imageId}/`;
const imageFileName = 'red-hot-chilli-peppers.jpg';

export default function () {
  // (...)
  this.post('/presign-aws-request', function () {
    return new Response(
      200,
      {},
      {
        url: s3BucketUrl,
        url_fields: {
          key: keyInBucket + '${filename}',
          success_action_status: '201',
          policy: '...', // the actual, serialized bucket policy
        },
      }
    );
  });

  this.post(s3BucketUrl, function (schema, request) {
    let key = request.requestBody
      .get('key')
      .replace('${filename}', imageFileName);

    let location = `${s3BucketUrl}/${encodeURIComponent(key)}`;
    return new Response(
      201,
      {
        Location: location,
      },
      `<PostResponse>
        <Location>${location}</Location>
        <Bucket>${bucketName}</Bucket>
        <Key>${keyInBucket}</Key>
        <ETag>"0af669d3f4786c05d779a0a7d44f6c61"</ETag>
      </PostResponse>
      `
    );
  });
}

I took the properties of an image that had been uploaded and used them as properties of the mock response, mimicking how the real endpoints work. The most important bit is the Location header of the AWS response since that's going to be set as the image-url property of the band.

After we've added the above handlers, the test passes fine:

Thinking about lying tests

Since we're testing against a mock back-end, let's pause for a moment to think through what exactly we are testing, or, more importantly, how could the test give us a false positive or negative.

How could the test give us false security? We always set the same image URL in the Location header and thus the same image-url will be set for the band, we don't know if the actual image that was uploaded will be properly assigned to the band object. If we were to introduce a bug to the Ember app which modifies the image-url somehow we wouldn't know because the Location is still sent back correctly.

However, if you look at the code again, you'll find that the Ember app doesn't alter any part of that URL, so that's not probable. This is done by our back-end (and S3) and should be tested there.

// app/components/band-form.js
export default class BandFormComponent extends Component {
  // (...)
  @action
  async save(event) {
    event.preventDefault();
    let bandProperties = {
      name: this.name,
    };

    if (this.imageToUpload) {
      let response = await fetch(`${ENV.apiHost}/presign-aws-request`, {
        method: 'POST',
      });
      let { url, url_fields: urlFields } = await response.json();

      let formData = new FormData();
      for (let field in urlFields) {
        formData.append(field, urlFields[field]);
      }
      formData.append('file', this.imageToUpload);

      let imageUploadResponse = await fetch(url, {
        method: 'POST',
        body: formData,
      });

      if (imageUploadResponse.ok) {
        bandProperties['image-url'] =
          imageUploadResponse.headers.get('Location');
        this.imageToUpload = null;
      }
    }

    return await this.args.onSave(bandProperties);
  }
}

A second, important scenario we're not currently testing is whether the image is too big to upload. Since that's done on the client-side, this has nothing to do with mocking, though, and we could test it by passing in "bytes" as the first argument of new File.

Let's now think about false negatives, the situation in which the test fails even though the feature works fine.

The only thing I can think of as a "false negative candidate" is the deletion of the hard-wired image from the S3 bucket. However, even though the image wouldn't display, the image-url would still be set and thus the assert.dom('[data-test-rr="band-image"]').exists() assertion would still pass.

With all of the above said, in "real" apps it's crucial to have end-to-end tests that don't switch out any of the architectural pieces so as to minimize the chance of tests not telling the truth.

Let's wrap up by writing a couple of tests for scenarios we haven't tested yet.

Test case for creating a band without an image

The bug I realized the app when I started to think about tests occurred when no image was uploaded for the band.

Let's write the test for this occurrence so that we don't regress on it:

// tests/acceptance/bands-test.js
// (...)
import { createBand } from 'rarwe/tests/helpers/custom-helpers';

module('Acceptance | bands', function (hooks) {
  // (...)
  test('Create a band — without image', async function (assert) {
    this.server.create('band', { name: 'Royal Blood' });

    await visit('/');
    await createBand({ name: 'Caspian' });

    await waitFor('[data-test-rr="no-songs-text"]');

    assert
      .dom('[data-test-rr="band-list-item"]')
      .exists({ count: 2 }, 'A new band link is rendered');
    assert
      .dom('[data-test-rr="band-list-item"]:last-child')
      .hasText('Caspian', 'The new band link is rendered as the last item');
    assert
      .dom('[data-test-rr="songs-nav-item"] > .active')
      .exists('The Songs tab is active');
  });
});

Test case for adding an image to an existing band

The other possibility to upload an image for a band is after creation, through editing the band:

// tests/acceptance/bands-test.js
// (...)
import { createBand } from 'rarwe/tests/helpers/custom-helpers';

module('Acceptance | bands', function (hooks) {
  // (...)
  test('Add image to band', async function (assert) {
    this.server.create('band', { name: 'Red Hot Chili Peppers' });

    let image = new File([], 'red-hot-chilli-peppers.jpg', {
      type: 'image/jpeg',
    });

    await visit('/');
    await click('[data-test-rr="band-link"]');
    await click('[data-test-rr="details-nav-item"] > a');
    await click('[data-test-rr="edit-band-link"]');
    await triggerEvent('[name="file-upload"]', 'change', { files: [image] });
    await click('[data-test-rr="save-band-button"]');

    assert.dom('[data-test-rr="band-image"]').exists('The band image is shown');
    assert
      .dom('[data-test-rr="details-nav-item"] > .active')
      .exists('The Details tab is active');
  });
});

Why do we need the `waitFor` calls?

Something that bothered me is that in several testing scenarios we needed to insert waitFor calls before we could assert the presence of DOM elements.

waitFors should only be needed in cases where Ember's testing framework can't figure it out on its own that it still needs to wait for some async operation. This could be the case when we integrate a 3rd-party library (like rendering a D3 graph) but it didn't seem like this was the case here.

It then occurred to me that when I save the band, I call await this.catalog.create('band', properties). This is a custom action in the catalog service I wrote and it calls fetch in its body. However, it doesn't use the fetch exported by ember-fetch which means the fetch is not run-loop aware and so Ember's test runner will not know to wait for it. The test runner moves on to the next line (which is usually an assertion) before the catalog.create could finish.

And indeed, simply putting the import fetch from 'fetch' as the first line in the catalog service makes the waitFor calls unnecessary.

Cool, we now have a decent test coverage for the image upload scenarios.

Uploading images to S3 in Ember.js – Part 3: Extracting a form component

2022-03-10T09:40:00+00:00

By the end of Part 2 of this series, we could create bands with a name and image whose size was validated to not be above a specific limit.

What's sorely missing from our implementation is that we can't edit existing bands, so we have no way to fix our errors or upload a band image later. We prepared the necessary work by having a dedicated page for editing bands and linking to it from the Details page.

In this part, we'll make managing the creation and editing of a band possible and maintainable.

Extract a form component

As we don't want to copy the form code for creating a new band and editing an existing one, we'll start by extracting the code we currently have in the controller and the related template into a component.

Let's start by creating a BandForm component, with a component class:

1$ ember g component band-form --with-component-class

The extraction should move the UI-related pieces from the controller to the new component but leave the saveBand action, and the logic around warning (or not) about unsaved changes as those belong in the invoking context.

That means our component will look like this:

// app/components/band-form.js
import Component from '@glimmer/component';
import { action } from '@ember/object';
import { tracked } from '@glimmer/tracking';
import fetch from 'fetch';

const MAX_IMAGE_SIZE_MB = 1;
const MAX_IMAGE_SIZE = MAX_IMAGE_SIZE_MB * 1024 * 1024;

export default class BandFormComponent extends Component {
  @tracked name;
  @tracked imagePreviewSrc;
  imageToUpload;

  @tracked validationError;

  @action
  updateName(event) {
    this.name = event.target.value;
  }

  @action
  didUploadImage(event) {
    this.validationError = '';
    let [file] = event.target.files;
    if (file.size > MAX_IMAGE_SIZE) {
      this.validationError = `Image should be smaller than ${MAX_IMAGE_SIZE_MB}MB.`;
      return;
    }
    this.imageToUpload = file;
    this.imagePreviewSrc = URL.createObjectURL(file);
  }

  @action
  async saveBand(event) {
    event.preventDefault();
    let response = await fetch('/presign-aws-request', {
      method: 'POST',
    });
    let { url, url_fields: urlFields } = await response.json();
    let bandProperties = {
      name: this.name,
    };

    let formData = new FormData();
    for (let field in urlFields) {
      formData.append(field, urlFields[field]);
    }
    formData.append('file', this.imageToUpload);

    let imageUploadResponse = await fetch(url, {
      method: 'POST',
      body: formData,
    });

    if (imageUploadResponse.ok) {
      bandProperties['image-url'] = imageUploadResponse.headers.get('Location');
      URL.revokeObjectURL(this.imageToUpload);
      this.imageToUpload = null;
    }

    return await this.args.onSave(bandProperties);
  }
}

(I renamed the this.saveBand to this.save in the component because the Band suffix is redundant in this context.)

While the controller code is reduced to the following:

 1// app/controllers/bands/new.js
 2import Controller from '@ember/controller';
 3import { action } from '@ember/object';
 4import { inject as service } from '@ember/service';
 5
 6export default class BandsNewController extends Controller {
 7  @service catalog;
 8  @service router;
 9
10  constructor() {
11    super(...arguments);
12    this.router.on('routeWillChange', (transition) => {
13      if (transition.isAborted) {
14        return;
15      }
16      if (this.confirmedLeave) {
17        return;
18      }
19      if (transition.from?.name === 'bands.new') {
20        if (this.name) {
21          let leave = window.confirm('You have unsaved changes. Are you sure?');
22          if (leave) {
23            this.confirmedLeave = true;
24          } else {
25            transition.abort();
26          }
27        }
28      }
29    });
30  }
31
32  G@action
33  async saveBand(properties) {
34    let band = await this.catalog.create('band', properties);
35    this.confirmedLeave = true;
36    this.router.transitionTo('bands.band.songs', band.id);
37  }
38}

The saveBand action now only contains what's specific to saving a band in this context. All the image-related URL fetching, composing the payload, and validating now live in the component where it will get reused when editing a band.

Consequently, the component template, band-form.hbs, is 99% identical to the template belonging to the controller, app/templates/bands/new.hbs. The only difference is that we call this.save instead of this.saveBand when submitting the form due to the name change I mentioned earlier.

The only thing remaining in the controller template is rendering the component:

{{!-- app/templates/bands/new.hbs --}}
<h3 class="text-lg leading-6 font-medium text-gray-100">
  New band
</h3>

<BandForm
  @onSave={{this.saveBand}}
/>

We managed to extract the component while the app works just as before:

Sorry, your browser doesn't support embedded videos.

Using the form component to edit bands

Now that we're armed with a BandForm component, we should also use it to allow editing an existing band which is the reason we extracted the component in the first place.

The main difference between using the component for creating and editing band objects is that we need to use the form with an existing band object in the latter case. So at the outset, we'll need to fetch it and pass it to the BandForm component to work with.

Let's generate a route (which also creates the corresponding template) for the "Edit band" page – we manually added a route entry for this page in the previous post:

1$  ember g route bands/edit-band

In the route, we fetch the band so that we can pass it into the component:

1// app/routes/bands/edit-band.js
2export default class BandsEditBandRoute extends Route {
3  @service catalog;
4
5  model(params) {
6    return this.catalog.find('band', (band) => band.id === params.id);
7  }
8}

{{!-- app/templates/bands/edit-band.hbs --}}
{{page-title "Edit " @model.name "| Rock & Roll with Octane" replace=true}}

<h3 class="text-lg leading-6 font-medium text-gray-100">
  Edit band
</h3>

<BandForm
  @band={{@model}}
  @onSave={{fn this.updateBand @model}}
/>

We assumed that an updateBand action exists in the context and that BandForm can handle a @band being passed in. Neither of these holds at the moment, so let's make them so.

updateBand needs to exist on the controller, which we'll first need to create:

1$  ember g controller bands/edit-band

The updateBand action should be very similar to the saveBand one in app/controllers/bands/new.js. Instead of creating a band, we should update the existing one:

 1// app/controllers/band/edit-band.js
 2import Controller from '@ember/controller';
 3import { action } from '@ember/object';
 4import { inject as service } from '@ember/service';
 5
 6export default class BandsEditBandController extends Controller {
 7  @service catalog;
 8  @service router;
 9
10  @action
11  async updateBand(band, attributes) {
12    await this.catalog.update('band', band, attributes);
13    this.router.transitionTo('bands.band.details', band.id);
14  }
15}

What's missing is that even though we pass the @band to the BandForm component on the Edit band page, we don't initialize the form taking that object into account. That means the form looks as if we were creating a band from scratch:

If we take another look at our form, it uses individual properties for each field (this.name, this.imagePreviewSrc) instead of using a form object. So to show the existing band properties in the fields, we need to initialize the form properties from them:

 1// app/components/band-form.js
 2export default class BandFormComponent extends Component {
 3  // (...)
 4  constructor() {
 5    super(...arguments);
 6    if (!this.args.band) {
 7      return;
 8    }
 9    let { name, imageUrl } = this.args.band;
10    this.name = name;
11    this.imagePreviewSrc = imageUrl;
12  }
13}

Perhaps somewhat surprisingly, that's the only change we need to apply to make this work:

Sorry, your browser doesn't support embedded videos.

A boring fix

When I said the above code change was the only change in the component's code to make the edit scenario work, it wasn't entirely true.

I needed to change some code in the catalog service for the update to work correctly. For the readers who have coded the Rock & Roll app and now follow along with this series also writing the code (if you're one of them, you're great!), they'll need to make the following code change:

// app/services/catalog.js
export default class CatalogService extends Service {
  // (...)
  async update(type, record, attributes) {
    // (...)
    let response = await fetch(url, {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/vnd.api+json',
      },
      body: JSON.stringify(payload),
    });
    let json = await response.json();
    return this.load(json);
  }

  add(type, record) {
    let collection = type === 'band' ? this.storage.bands : this.storage.songs;
    let existingIndex = collection.findIndex((r) => record.id === r.id);
    if (existingIndex === -1) {
      collection.push(record);
    } else {
      collection.splice(existingIndex, 1, record);
    }
  }
}

There are still fascinating further improvements to make, some of which I'm planning to write about. Removing or replacing the band image, post-processing the uploaded image, and testing the image upload come to mind at first, but I'm sure we could add several other features.

Until next time!

Balint Erdi's tech blog

The Rock & Roll with Ember band - Michal Bryxí

Could you introduce yourself in a few sentences?

Which part of the world are you from?

When and how did your Ember journey begin? How did you learn about the framework?

How did reading the Rock & Roll with Ember book help you? Can you recall something that you learned from it?

Other than reading the book, how did you learn to “speak" Ember?

What Ember feature/RFC/etc. are you most excited about?

Is there something you’d like to see covered or explained in more detail in the book?

Are there any (side-)projects that you’ve built in Ember? What is it (are they) about?

Were there any challenges or stumbling blocks while you were building your app(s)?

What do you like to do in your free time?

If people would like to follow you (or your project), where can they do so?

Is there something else you’d like to say?

Testing async DOM functions in Ember.js - a custom waiter alternative

Buying just a little bit of time

Wait for it

Custom waiter vs. waitFor

Testing async DOM functions in Ember.js

Showing an avatar – or the initials

What do test helpers wait for?

Adding a custom test waiter

Covering the happy path

Adding code to make something testable

Does settled settle it?

Using simple functions as helpers in Ember.js

A simple currency converter

Allowing to change the base currency

Formatting currencies (well, numbers)

Extracting the function to be reused

Is there still a place for "classic" template helpers?

Functional helpers

Class-based helpers

A note on currency formatting

Which one to use?

Uploading images to S3 in Ember.js – Part 4: Testing

Existing test for creating a band

A bug revealed

Writing new tests

Test case for creating a band with an image

Thinking about lying tests

Test case for creating a band without an image

Test case for adding an image to an existing band

Why do we need the waitFor calls?

Uploading images to S3 in Ember.js – Part 3: Extracting a form component

Extract a form component

Using the form component to edit bands

A boring fix

Does `settled` settle it?

Why do we need the `waitFor` calls?