DEV Community: Evan Schultz (he/him)

Preparing to Launch

Evan Schultz (he/him) — Thu, 28 May 2020 23:07:18 +0000

Test

How to Create Data-Driven User Interfaces in Vue

Evan Schultz (he/him) — Sat, 04 Apr 2020 18:46:59 +0000

Although we usually know what components are needed when building most views within an app, sometimes we don't know what they are until runtime.

This means we need to build a screen based on the application state, user preferences, or response from an API. A common case is creating dynamic forms, where the questions and components needed are either configured by a JSON object, or where fields change based on the users' answers.

All modern JavaScript frameworks have ways of handling dynamic components. This blog post will show you how to do it in Vue.JS, which provides a remarkably elegant and easy solution to the above scenario.

Once you see how easy this can be using Vue.JS, you might get inspired and see applications for dynamic components that you have never considered before!

We need to walk before we can run, so first I'll go over the basics of dynamic components, and then dive into how these concepts can be used to build your own dynamic form builder.

The Basics

Vue has a built-in component called (fittingly) <component>. You can see the full details in the VueJS guide on Dynamic Components.

The guide says:

"You can use the same mount point and dynamically switch between multiple components using the reserved element and dynamically bind to its is attribute."

What this means is that being able to swap between components can be as simple as:

<component :is="componentType">

Let's flesh this out a bit more and see what is going on. We will create two components called DynamicOne and DynamicTwo - for now One and Two will be the same, so I won’t repeat the code for both:

<template>
  <div>Dynamic Component One</div>
</template>
<script>
export default {
  name: 'DynamicOne',
}
</script>

For a quick example of being able to toggle between them, in our App.vue we will set up our component:

import DynamicOne from './components/DynamicOne.vue'
import DynamicTwo from './components/DynamicTwo.vue'

export default {
  name: 'app',
  components: {
    DynamicOne, DynamicTwo
  },
  data() {
    return {
      showWhich: 'DynamicOne'
    }
  }
}

Note: the showWhich data property is the string value of DynamicOne - this is the property name created in the components object on the component.

In our template, we will set up two buttons to swap between the two dynamic components:

<button @click="showWhich = 'DynamicOne'">Show Component One</button>
<button @click="showWhich = 'DynamicTwo'">Show Component Two</button>

<component :is="showWhich"></component>

Clicking on the buttons will swap out DynamicOne with DynamicTwo.

At this point, you might be thinking, “Well, so what? That’s handy - but I could have used v-if just as easily.”

This example starts to shine when you realize that <component> works just like any other component, and it can be used in combination with directives like v-for for iterating over a collection, or making the :is bindable to an input prop, data prop, or computed property.

What about the props and events?

Components don’t live in isolation - they need a way to communicate with the world around them. With Vue, this is done with props and events.

You can specify property and event bindings on a dynamic component the same way as any other component, and if the component that gets loaded does not need that property, Vue will not complain about unknown attributes or properties.

Let's modify our components to display a greeting. One will accept just firstName and lastName, while another will accept firstName, lastName and title.

For the events, we will add a button in DynamicOne that will emit an event called ‘upperCase’, and in DynamicTwo, a button that will emit an event ‘lowerCase’.

Putting it together, consuming the dynamic component starts to look like:

<component 
    :is="showWhich" 
    :firstName="person.firstName"
    :lastName="person.lastName"
    :title="person.title"
    @upperCase="switchCase('upperCase')"
    @lowerCase="switchCase('lowerCase')">
</component>

Not every property or event needs to be defined on the dynamic component that we are switching between.

Do you need to know all the props upfront?

At this point, you might be wondering, "If the components are dynamic, and not every component needs to know every possible prop - do I need to know the props upfront, and declare them in the template?"

Thankfully, the answer is no. Vue provides a shortcut, where you can bind all the keys of an object to props of the component using v-bind.

This simplifies the template to:

<component 
    :is="showWhich" 
    v-bind="person"
    @upperCase="switchCase('upperCase')"
    @lowerCase="switchCase('lowerCase')">
</component>

What about Forms?

Now that we have the building blocks of Dynamic Components, we can start building on top of other Vue basics to start building a form generator.

Let's start with a basic form schema - a JSON object that describes the fields, labels, options, etc for a form. To start, we will account for:

Text and Numeric input fields
A Select list

The starting schema looks like:

schema: [{
    fieldType: "SelectList",
    name: "title",
    multi: false,
    label: "Title",
    options: ["Ms", "Mr", "Mx", "Dr", "Madam", "Lord"],
  },
  {
    fieldType: "TextInput",
    placeholder: "First Name",
    label: "First Name",
    name: "firstName",
  },
  {
    fieldType: "TextInput",
    placeholder: "Last Name",
    label: "Last Name",
    name: "lastName",
  },
  {
    fieldType: "NumberInput",
    placeholder: "Age",
    name: "age",
    label: "Age",
    minValue: 0,
  },
]

Pretty straightforward - labels, placeholders, etc - and for a select list, a list of possible options.

We will keep the component implementation for these simple for this example.

TextInput.vue

<template>
<div>
    <label>{{label}}</label>
    <input type="text"
         :name="name"
          placeholder="placeholder">
</div>
</template>
<script>
export default {
  name: 'TextInput',
  props: ['placeholder', 'label', 'name']
}
</script>

SelectList.vue

<template>
  <div>
    <label>{{label}}</label>
    <select :multiple="multi">
      <option v-for="option in options"
              :key="option">
        {{option}}
      </option>
    </select>
  </div>
</template>
<script>
export default {
  name: 'SelectList',
  props: ['multi', 'options', 'name', 'label']
}
</script>

To generate the form based on this schema, add this:

<component v-for="(field, index) in schema"
  :key="index"
  :is="field.fieldType"
  v-bind="field">
</component>

Which results in this form:

Data Binding

If a form is generated but does not bind data, is it very useful? Probably not. We currently are generating a form but have no means of binding data to it.

Your first instinct might be to add a value property to the schema, and in the components use v-model like so:

<input type="text" 
    :name="name"
    v-model="value"
    :placeholder="placeholder">

There are a few potential pitfalls with this approach, but the one that we care about most is one that Vue will give us an error/warning about:

[Vue warn]: Avoid mutating a prop directly since the value will be overwritten whenever the parent component re-renders. Instead, use a data or computed property based on the prop's value. Prop being mutated: "value"

found in

---> <TextInput> at src/components/v4/TextInput.vue
       <FormsDemo> at src/components/DemoFour.vue
         <App> at src/App.vue
           <Root>

While Vue does provide helpers to make the two-way binding of component state easier, the framework still uses a one-way data flow. We have tried to mutate the parent's data directly within our component, so Vue is warning us about that.

Looking a little more closely at v-model, it does not have that much magic to it, so let's break it down as described in the [Vue Guide on Form Input Components](https://vuejs.org/v2/guide/components-custom-events.html#Binding-Native-Events-to-Components_.

<input v-model="something">

Is similar to:

<input
  v-bind:value="something"
  v-on:input="something = $event.target.value">

With the magic revealed, what we want to accomplish is:

Let the parent provide the value to the child component
Let the parent know that a value has been updated

We accomplish this by binding to the :value and emitting an @input event to notify the parent that something has changed.

Let's look at our TextInput component:

 <div>
  <label>{{ label }}</label>
  <input
    type="text"
    :name="name"
    :value="value"
    @input="$emit('input',$event.target.value)"
    :placeholder="placeholder"
  />
</div>

Since the parent is responsible for providing the value, it is also responsible for handling the binding to its own component state. For this we can use v-model on the component tag:

FormGenerator.vue

<component v-for="(field, index) in schema"
    :key="index"
    :is="field.fieldType"
    v-model="formData[field.name]"
    v-bind="field">
</component>

Notice how we are using v-model="formData[field.name]". We need to provide an object on the data property for this:

export default {
  data() {
    return {
      formData: {
        firstName: 'Evan'
      },
}

We can leave the object empty, or if we have some initial field values that we want to set up, we could specify them here.

Now that we have gone over generating a form, it’s starting to become apparent that this component is taking on quite a bit of responsibility.

While this is not complicated code, it would be nice if the form generator itself was a reusable component.

Making the Generator Reusable

For this form generator, we will want to pass the schema to it as a prop and be able to have data-binding set up between the components.

When using the generator, the template becomes:

GeneratorDemo.vue

<form-generator :schema="schema" v-model="formData">
</form-generator>

This cleans up the parent component quite a bit. It only cares about FormGenerator, and not about each input type that could be used, wiring up events, etc.

Next, make a component called FormGenerator. This will pretty much be copy-pasted of the initial code with a few minor, but key tweaks:

Change from v-model to :value and @input event handling
Add props value and schema
Implement updateForm

The FormGenerator component becomes:

FormGenerator.vue

<template>
  <component v-for="(field, index) in schema"
             :key="index"
             :is="field.fieldType"
             :value="formData[field.name]"
             @input="updateForm(field.name, $event)"
             v-bind="field">
    </component>
</template>
<script>
import NumberInput from '@/components/v5/NumberInput'
import SelectList from '@/components/v5/SelectList'
import TextInput from '@/components/v5/TextInput'

export default {
  name: "FormGenerator",
  components: { NumberInput, SelectList, TextInput },
  props: ['schema', 'value'],
  data() {
    return {
      formData: this.value || {}
    };
  },
  methods: {
    updateForm(fieldName, value) {
      this.$set(this.formData, fieldName, value);
      this.$emit('input', this.formData)
    }
  }
};
</script>

Since the formData property does not know every possible field that we could pass in, we want to use this.$set so Vue's reactive system can keep track of any changes, and allow the FormGenerator component to keep track of its own internal state.

Now we have a basic, reusable form generator.

Using the Generator

<template>
  <form-generator :schema="schema" v-model="formData">
  </form-generator>
</template>
<script>
import FormGenerator from '@/components/v5/FormGenerator'

export default {
  name: "GeneratorDemo",
  components: { FormGenerator },
  data() {
    return {
      formData: {
        firstName: 'Evan'
      },
      schema: [{ /* .... */ },
}
</script>

So now that you've seen how a form generator can leverage the basics of dynamic components in Vue to create some highly dynamic, data-driven UIs,

I encourage you to play around with this example code on GitHub, or experiment on [CodeSandbox]. And feel free to reach out if you have any questions or want to talk shop, comment below or reach out on:

Twitter: @e_p82
GitHub: e-schultz
LinkedIn: eschultz1

note: This was initially published on the rangle.io blog on March 7, 2018

Are Your Unit Tests Failing for the Expected Reasons?

Evan Schultz (he/him) — Wed, 11 Dec 2019 13:16:56 +0000

Unit tests can be an invaluable tool in the developers toolbox. You don't need to be a strict TDD purist to make unit testing worthwhile. Once you get into the flow of writing tests, it can be rather satisfying to watch the Nyan Cat Reporter go across your screen as the number of tests passing increase.

As with any other tool though, it can be misused, and not always provide the benefit that you want or expect.

The other day I was doing some code clean up, and came across a test that started to make me ask questions instead of having them answered.

Some of the questions that a unit test should be answering:

What is it testing?
What is it doing?
What is expected behavior?
What is the actual behavior?
Does it pass or fail for the expected reasons?

The test that made me go 'hrmm?' looked something like this:

/// .... mock removed for now

it('should call /location/calculate-distance correctly', () =>
   locationApi.calculateDistance(10,20,30,40).then(res => {
     expect(res.distance).to.equal('ok');
   })
 );

Reading this unit test, it's not really clear what is actually being tested. The it block is saying that it should call /location/calculate-distance correctly, but the expect at the bottom is looking at the response.

Currently this test is passing, but it's not passing for a reason that the test states it should be. Yes, there is something responding, but response.distance being ok has nothing to do with the behavior we wanting to verify.

This application was using ismorphic-fetch and fetch-mock to mock out HTTP requests. The mock for this test looks like:

before(() => {
  fetchMock
  .mock(
    (url, options) =>
      url === [
        LOCATION_ENDPOINT,
        'calculate-distance?&lat1=10&long1=20&lat2=30&long2=40',
      ].join('/')
      && options.method === 'GET',
    {
      body: JSON.stringify({ distance: 'ok' }),
      status: 200,
      headers: { 'content-type': 'application/json' },
    }
  );
});

This starts to give a bit more insight, and after digging around that was going on in locationApi.calculateDistance - it seems like this test is wanting to verify that for a given set of parameters, the URL is formed up correctly to query the API to calculate the distance.

When the test runs, it currently passes. If it fails though, am I getting useful information? If I tweak the location code in how it forms the URL, the errors that get reported look like:

1) api/location should call /location/calculate-distance correctly:
     Error: only absolute urls are supported
      at node_modules/node-fetch/index.js:54:10
      at new Fetch (node_modules/node-fetch/index.js:49:9)
      at Fetch (node_modules/node-fetch/index.js:37:10)
      at module.exports (node_modules/isomorphic-fetch/fetch-npm-node.js:8:19)
      at FetchMock.fetchMock (node_modules/fetch-mock/src/fetch-mock.js:265:17)
      at exports.default (src/api/helpers/composer-request.js:14:12)
      at Object.exports.getTaxEstimate (src/api/location-api.js:8:10)
      at Context.<anonymous> (src/api/location-api.test.js:27:13)

And hidden away at the top of the unit tests running and easy to miss, is:

api/location
unmatched call to /location!calculate-distance?lat1=10&long1=20&lat2=30&long2=40

This isn't terribly useful information. The error that is getting reported doesn't tell me anything about what the expected and actual results were.

Error: only absolute urls are supported

This is an error thrown by fetch-mock before our expect statements have even been hit. There is a hint at the top of the unit test reports where fetch-mock will complain about an unmatched call.

This message is easy to miss, and it also requires the person reading the unit test results to understand a bit of how fetch-mock works get pointed in the right direction.

For a seemingly simple unit test, it asks more questions than it answers.

A more accurate description of this test would be:

describe('fetch-mock behavior', () => {
  it('should return the object I told it to if no error is thrown', () => {

  });
});

If we were the authors of fetch-mock, that could possibly be a useful test. But, we are wanting to write unit tests for the system we are building, not for the mocking frameworks we are using.

The fact that expect(res.distance).to.equal('ok'); is more of a coincidence than the behavior you want to test.

What can we do to make it clear what the intended purpose of this test is, and that it provides meaningful errors when it fails?

Let's revisit the questions we asked at the start, and clean up the test to start answering them.

What is it testing?

When the calculateDistance is called, then an API is called with a specific URL and query parameters. The response object is inconsequential here. Let's adjust the unit test to start being more descriptive and accurate.

it('should call calculate-distance with correct query parameters', () => {  
  //
});

The 'it' sentence starts to describe what we are doing without needing to read the test body.

What is it doing?

The initial test wasn't that bad at answering this one, it's calling the locationApi.calculateDistance,

it('should call calculate-distance with correct query parameters', () => {  
  return locationApi
  .calculateDistance(10,20,30,40)
  .then(() => {
    // ..
  });
});

What is the expected / actual behavior

This is where the previous test started to fail at answering these questions.

We don't care if the response object has a distance of 'ok', we want to verify the URL that is being hit.

In answering this question, we can state what the expected and actual results are.

it('should call calculate-distance with correct query parameters', () => {  
  const EXPECTED_URL = `${LOCATION_ENDPOINT}/calculate-distance?lat1=10&long1=20&lat2=30&long2=40`;
  return locationApi
  .calculateDistance(10,20,30,40)
  .then(() => {
    const ACTUAL_URL = fetchMock.lastUrl();
    expect(EXPECTED_URL).to.equal(ACTUAL_URL);
  });
});

Now when reading the unit test, the expected reasons for passing/failing are more obvious. The thing that I am asserting is reflective of the behavior that I want.

However, if the test fails, the output still isn't very useful and still complains about: Error: only absolute urls are supported

This leads to answering the final question:

Does it pass or fail for the expected reasons?

Currently fetch-mock is throwing an error before we even hit our expect statement, so we can't guarantee that things are passing or failing for the reasons we expect.

Adjusting our mock is pretty straightforward. Instead of having the mock be very specific for a URL, I am adjusting it to match just about anything that begins with a slash.

before(() =>fetchMock.mock(`^/`,
   { body: JSON.stringify({ data: 'ok' }),
     status: 200,
     headers: { 'content-type': 'application/json' },
   }));

When we run our test and if it fails, the error that gets reported is now:

1) should call calculate-distance with correct query parameters:

      AssertionError: expected '/location!calculate-distance?lat1=10&long1=20&lat2=30&long2=40' to equal '/location/calculate-distance?lat1=10&long1=20&lat2=30&long2=40'
      + expected - actual

      -/location!calculate-distance?lat1=10&long1=20&lat2=30&long2=40
      +/location!calculate-distance?lat1=10&long1=20&lat2=30&long2=40

      at src/api/location-api.test.js:21:29
      at process._tickCallback (internal/process/next_tick.js:103:7)

With a few minor changes to the unit test and the mock, the test is starting to answer questions, instead of making us ask them.

The mock has been simplified and is easier to understand.
The expect statement makes it clear the behavior that we are testing.
The test fails for the correct reason - actual does not meet expected behavior.
When the test fails, it is descriptive to what the error is.

Next time you're writing a unit test or reviewing others, maybe double check to ensure that they are passing or failing for the reasons that you expect.

If reading a unit test makes you ask questions, then it could be a sign that you need to clean them up to make them more useful.

initially posted on the rangle.io blog

Improving your mental model of useEffect

Evan Schultz (he/him) — Wed, 11 Dec 2019 12:55:15 +0000

Hooks landed in React a few months ago, and there has been a lot of excitement around them in terms of figuring out how to best use them, best practices, and how they map to current concepts in React and the lifecycle.

Many React developers are familiar with the React Component lifeCycle, and hooks like:

etc.

When trying to understand the useEffect hook, it's natural to want to map it to the lifecycle methods we already know. At first glance, useEffect seems to be like a combination of componentDidMount and componentDidUpdate.

While this can be a useful way of looking at it at first, it may not be the most accurate.

Instead of thinking in terms of 'what do I want to do when I mount, or when I update', it's more useful to ask:

What values does this effect depend on?

To better understand where the idea of useEffect = componentDidMount + componentDidUpdate comes from, we will first look at a typical class-based component that is doing some data fetching.

export default SearchComponent extends Component {
  constructor(props) {
    super(props);
    this.state = {
      results: []
    }
  }
  componentDidMount() {
    this.query(this.props.id)
  }
  componentDidUpdate(prevProps) {
    if(this.prevProps.id !== this.props.id) {
      this.query(this.props.id);
    }
  }
  query(id) {
    this.setState({isLoading: true})
    fetch(`/some/url/${id}`)
      .then(r=>r.json())
      .then(r=>this.setState({
        results: results
      });
    )
  }
}

When the component first mounts, we fetch data for the id that has been passed down as a prop. When the component updates, many things other than the id prop changing can cause this method to run, so we want to ensure that id has actually changed - or some poor server is going to get a DDoS attack with a bunch of API calls that we don't need.

While the lifecycle hooks of componentDidMount and componentDidUpdate with class-based components are common places to make a request based on a property, the fact that the component is mounting or updating is not really the thing we are concerned with.

What we are actually concerned with?

"what data does the query depend on?"

Before looking at how to handle this with useEffect, lets quickly review the API of useEffect:

Accepts a function
If it returns a function, it will do cleanup when the component is unmounted
Has an optional 2nd argument to pass in the data it depends on

One of the key things to keep in mind is the importance of that second argument, the React Docs go into this in detail, but a summary is:

If we leave it blank - it will run on every single render.
If we pass in an empty array - it will execute only when the component mounts, and not on any updates
If we pass in a value - it will execute when any of those values change
If you are using the react-hooks eslint plugin (and you should) - not providing the dependencies to your useEffect will give you warnings.

export default SomeComponent = ({id}) => {
  let [results, setResults] = useState([]);
  useEffect(()=>{
    fetch(`/some/url/${id}`)
      .then(r=>r.json())
      .then(r=>setResults(r))
  },[id])
}

In the class-based version, making API calls feels very imperative - when this method is called, I want to check if/how a value has changed, and if it has changed - I want to call a method.

If the component is being created or updated often isn't the thing the matters. What we actually care about is "has the values that I care about changed?".

Before hooks were introduced, componentDidMount and componentDidUpdate were the best tools for the job at the time.
With the hook based version, we are able to express this intent in a more declarative way: "I want to fetch data when the id changes"

How do we identify what the effect depends on?

The eslint plugin can guide you in the right direction, but the short version is: "is there a variable that impacts how we run the effect?" If so, add it to the dependencies.

To demonstrate this, let's add an extra query parameter to our search:

export default SomeComponent = ({id, filter}) => {
  let [results, setResults] = useState([]);

  useEffect(()=>{
    fetch(`/some/url/${id}?filter=${filter}`)
      .then(r=>r.json())
      .then(r=>setResults(r))
  },[id])
}

Even though we have added filter to the fetch query string, we have not added it to the dependencies of useEffect.

As we update the filter, we won't be calling the API on any of the other updates, and it will only run when the id has changed.

Fixing this can be simple enough - add the filter to the list of dependencies for the useEffect.

export default SomeComponent = ({id, filter}) => {
  let [results, setResults] = useState([]);

  useEffect(()=>{
    fetch(`/some/url/${id}?filter=${filter}`)
      .then(r=>r.json())
      .then(r=>setResults(r))
  },[id, filter])
}

As you can see, to properly use useEffect, in this case, we don't care if the component is mounting, or updating, or where it is in the life cycle.

What we do care about is what data does this effect depend on.

useEffect is a very useful tool to add to our toolbox when working with React, but it can also be one of the more difficult hooks to fully understand.

Hopefully, this post can help clarify things a little bit better, but if you are curious for a deeper dive, be sure to check out Dan Abramovs' post, A Complete Guide to useEffect

this article was initially posted on the rangle.io blog and medium