The latest articles on DEV Community by Isaac Lee (@ijlee2). https://dev.to/ijlee2 https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F86322%2Fbfa4a0cf-d246-4df6-8c36-3c45f6093a50.jpeg https://dev.to/ijlee2 en Isaac Lee Mon, 13 Oct 2025 12:20:47 +0000 https://dev.to/ijlee2/migrating-to-tag-39on https://dev.to/ijlee2/migrating-to-tag-39on <p><code>&lt;template&gt;</code> tag lets us write template(s) in <a href="https://rfcs.emberjs.com/id/0496-handlebars-strict-mode/" rel="noopener noreferrer">strict mode</a>. Templates are more explicit and statically analyzable, so we can adopt more tools from the JavaScript ecosystem. There's less work for Embroider to do, so we can expect app builds to be faster.</p> <p><code>&lt;template&gt;</code> tag has been around for a few years now. With the help of addons, <a href="https://github.com/ember-cli/ember-template-imports" rel="noopener noreferrer">in components and tests</a> since 2020 and <a href="https://github.com/discourse/ember-route-template" rel="noopener noreferrer">in routes</a> since 2023. In short, it's stable and you can likely use <code>&lt;template&gt;</code> tag in your projects today.</p> <p>This post aims to accelerate adoption. I will show you step-by-step how to migrate an existing component, route, and test. Once you understand the idea, feel free to <a href="https://github.com/ijlee2/ember-codemod-add-template-tags" rel="noopener noreferrer">run my codemod</a> to automate the steps.</p> <h2> 1. Where did things come from? </h2> <p>To enter strict mode, we will be importing objects (e.g. components, helpers, modifiers) instead of letting string names in templates be somehow resolved. So let's first look at where things come from.</p> <div class="table-wrapper-paragraph"><table> <thead> <tr> <th>Package</th> <th>Objects</th> </tr> </thead> <tbody> <tr> <td><code>@ember/component</code></td> <td>Input, Textarea</td> </tr> <tr> <td><code>@ember/helper</code></td> <td>array, concat, fn, get, hash, uniqueId</td> </tr> <tr> <td><code>@ember/modifier</code></td> <td>on</td> </tr> <tr> <td><code>@ember/routing</code></td> <td>LinkTo</td> </tr> <tr> <td><code>@ember/template</code></td> <td>htmlSafe</td> </tr> <tr> <td><code>@embroider/util</code></td> <td>ensureSafeComponent</td> </tr> </tbody> </table></div> <p>The right column shows objects native to Ember. We name-import them from the path shown in the left. For example,<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="k">import</span> <span class="p">{</span> <span class="nx">array</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">@ember/helper</span><span class="dl">'</span><span class="p">;</span> </code></pre> </div> <p>Notice, there's a naming convention:</p> <ul> <li>Component names follow Pascal case. (Capitalize the first letter of each word.)</li> <li>All other names follow camel case.</li> </ul> <p>For Ember addons, you can always do a default-import. However, for each object, you have to remember the full path, add 1 line of code, and type many characters. It's also easy to introduce inconsistencies in the import name (the "local" name).<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="k">import</span> <span class="nx">ContainerQuery</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ember-container-query/components/container-query</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="nx">height</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ember-container-query/helpers/height</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="nx">width</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ember-container-query/helpers/width</span><span class="dl">'</span><span class="p">;</span> </code></pre> </div> <p>Due to these reasons, always do name-imports when an addon provides a barrel file. If it doesn't, consider making a pull request.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="k">import</span> <span class="p">{</span> <span class="nx">ContainerQuery</span><span class="p">,</span> <span class="nx">height</span><span class="p">,</span> <span class="nx">width</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ember-container-query</span><span class="dl">'</span><span class="p">;</span> </code></pre> </div> <h2> 2. How to migrate </h2> <p>We will consider a component just complex enough to cover the important steps. You can use <a href="https://github.com/ijlee2/ember-workshop" rel="noopener noreferrer">ember-workshop</a> to test the code shown below. <code>&lt;Hello&gt;</code> is defined in <code>my-addon</code>, then rendered and tested in <code>my-app</code>.</p> <h3> a. Components </h3> <p><code>&lt;Hello&gt;</code> is a Glimmer component that receives 1 argument. For simplicity, we will ignore the component signature.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight css"><code><span class="c">/* my-addon: src/components/hello.module.css */</span> <span class="nc">.container</span> <span class="p">{</span> <span class="nl">color</span><span class="p">:</span> <span class="no">orange</span><span class="p">;</span> <span class="nl">font-style</span><span class="p">:</span> <span class="nb">italic</span><span class="p">;</span> <span class="p">}</span> <span class="nc">.hide</span> <span class="p">{</span> <span class="nl">animation</span><span class="p">:</span> <span class="n">fade-out</span> <span class="m">0s</span> <span class="n">ease-in</span> <span class="m">0s</span> <span class="n">forwards</span><span class="p">;</span> <span class="p">}</span> <span class="nc">.hide.after-3-sec</span> <span class="p">{</span> <span class="nl">animation-delay</span><span class="p">:</span> <span class="m">3s</span><span class="p">;</span> <span class="p">}</span> <span class="k">@keyframes</span> <span class="n">fade-out</span> <span class="p">{</span> <span class="nt">to</span> <span class="p">{</span> <span class="nl">height</span><span class="p">:</span> <span class="m">0</span><span class="p">;</span> <span class="nl">overflow</span><span class="p">:</span> <span class="nb">hidden</span><span class="p">;</span> <span class="nl">width</span><span class="p">:</span> <span class="m">0</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre> </div> <div class="highlight js-code-highlight"> <pre class="highlight handlebars"><code><span class="c">{{! my-addon: src/components/hello.hbs }}</span> <span class="nt">&lt;div</span> <span class="na">class=</span><span class="k">{{</span><span class="nv">local</span> <span class="nv">this</span><span class="p">.</span><span class="nv">styles</span> <span class="s2">"container"</span> <span class="p">(</span><span class="nv">if</span> <span class="nv">this</span><span class="p">.</span><span class="nv">someCondition</span> <span class="p">(</span><span class="nv">array</span> <span class="s2">"hide"</span> <span class="s2">"after-3-sec"</span><span class="p">))</span> <span class="k">}}</span> <span class="nt">&gt;</span> <span class="k">{{</span><span class="nv">t</span> <span class="s2">"hello.message"</span> <span class="nv">name</span><span class="o">=</span><span class="na">@name</span><span class="k">}}</span> <span class="nt">&lt;/div&gt;</span> </code></pre> </div> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="cm">/* my-addon: src/components/hello.ts */</span> <span class="k">import</span> <span class="nx">Component</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">@glimmer/component</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="nx">styles</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">./hello.module.css</span><span class="dl">'</span><span class="p">;</span> <span class="kr">interface</span> <span class="nx">HelloSignature</span> <span class="p">{</span> <span class="nl">Args</span><span class="p">:</span> <span class="p">{</span> <span class="na">name</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="p">};</span> <span class="p">}</span> <span class="k">export</span> <span class="k">default</span> <span class="kd">class</span> <span class="nc">Hello</span> <span class="kd">extends</span> <span class="nc">Component</span><span class="o">&lt;</span><span class="nx">HelloSignature</span><span class="o">&gt;</span> <span class="p">{</span> <span class="nx">styles</span> <span class="o">=</span> <span class="nx">styles</span><span class="p">;</span> <span class="kd">get</span> <span class="nf">someCondition</span><span class="p">():</span> <span class="nx">boolean</span> <span class="p">{</span> <span class="k">return</span> <span class="kc">true</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre> </div> <p>1. Change the class' file extension to <code>.gts</code>. Insert an empty <code>&lt;template&gt;</code> tag at the end of the class body.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-addon: src/components/hello.gts */ <span class="p">import Component from '@glimmer/component'; </span><span class="err"> </span><span class="p">import styles from './hello.module.css'; </span><span class="err"> </span><span class="p">export default class Hello extends Component&lt;HelloSignature&gt; { </span> styles = styles; <span class="err"> </span> get someCondition(): boolean { return true; } <span class="gi">+ + &lt;template&gt; + &lt;/template&gt; </span>} </code></pre> </div> <p>2. Copy the template from <code>.hbs</code> and paste it into the <code>&lt;template&gt;</code> tag. Delete the <code>.hbs</code> file afterwards.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-addon: src/components/hello.gts */ <span class="p">import Component from '@glimmer/component'; </span><span class="err"> </span><span class="p">import styles from './hello.module.css'; </span><span class="err"> </span><span class="p">export default class Hello extends Component&lt;HelloSignature&gt; { </span> styles = styles; <span class="err"> </span> get someCondition(): boolean { return true; } <span class="err"> </span> &lt;template&gt; <span class="gi">+ &lt;div + class={{local + this.styles + "container" + (if this.someCondition (array "hide" "after-3-sec")) + }} + &gt; + {{t "hello.message" name=@name}} + &lt;/div&gt; </span> &lt;/template&gt; } </code></pre> </div> <p>3. Enter strict mode. That is, specify where things come from.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-addon: src/components/hello.gts */ <span class="gi">+ import { array } from '@ember/helper'; </span><span class="p">import Component from '@glimmer/component'; </span><span class="gi">+ import { t } from 'ember-intl'; + import { local } from 'embroider-css-modules'; </span><span class="err"> </span><span class="p">import styles from './hello.module.css'; </span><span class="err"> </span><span class="p">export default class Hello extends Component&lt;HelloSignature&gt; { </span> styles = styles; <span class="err"> </span> get someCondition(): boolean { return true; } <span class="err"> </span> &lt;template&gt; &lt;div class={{local this.styles "container" (if this.someCondition (array "hide" "after-3-sec")) }} &gt; {{t "hello.message" name=@name}} &lt;/div&gt; &lt;/template&gt; } </code></pre> </div> <p>4. (Optional) Remove unnecessary code. Examples include:</p> <ul> <li>Constants passed to the template via the class</li> <li>Template registry (the <code>declare module</code> block), if you no longer have to support <code>*.hbs</code> files or <code>hbs</code> tags.</li> <li> <code>ensureSafeComponent()</code> from <code>@embroider/util</code> (pass the component directly)</li> <li>One-off helpers </li> </ul> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-addon: src/components/hello.gts */ <span class="p">import { array } from '@ember/helper'; import Component from '@glimmer/component'; import { t } from 'ember-intl'; import { local } from 'embroider-css-modules'; </span><span class="err"> </span><span class="p">import styles from './hello.module.css'; </span><span class="err"> </span><span class="p">export default class Hello extends Component&lt;HelloSignature&gt; { </span><span class="gd">- styles = styles; - </span> get someCondition(): boolean { return true; } <span class="err"> </span> &lt;template&gt; &lt;div class={{local <span class="gd">- this.styles </span><span class="gi">+ styles </span> "container" (if this.someCondition (array "hide" "after-3-sec")) }} &gt; {{t "hello.message" name=@name}} &lt;/div&gt; &lt;/template&gt; } </code></pre> </div> <p>Note, we pass the signature of a Glimmer component to the base class <code>Component</code>. For template-only components, we can provide the signature in two ways:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>/* my-addon: src/components/hello.gts */ import type { TOC } from '@ember/component/template-only'; import { t } from 'ember-intl'; import styles from './hello.module.css'; const Hello: TOC&lt;HelloSignature&gt; = &lt;template&gt; &lt;div class={{styles.container}}&gt; {{t "hello.message" name=@name}} &lt;/div&gt; &lt;/template&gt;; export default Hello; </code></pre> </div> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>/* my-addon: src/components/hello.gts */ import type { TOC } from '@ember/component/template-only'; import { t } from 'ember-intl'; import styles from './hello.module.css'; &lt;template&gt; &lt;div class={{styles.container}}&gt; {{t "hello.message" name=@name}} &lt;/div&gt; &lt;/template&gt; satisfies TOC&lt;HelloSignature&gt;; </code></pre> </div> <p>The first variation (assigns the template to a variable, uses type annotation) may help with debugging and searching code, as the variable gives a name to the component. The second (no assignment, use of <code>satisfies</code>) is what Ember CLI currently uses in its blueprints.</p> <h3> b. Routes </h3> <p>In <code>my-app</code>, the <code>index</code> route renders <code>&lt;Hello&gt;</code>:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight handlebars"><code><span class="c">{{! my-app: app/templates/index.hbs }}</span> <span class="nt">&lt;div</span> <span class="na">class=</span><span class="k">{{</span><span class="nv">this</span><span class="p">.</span><span class="nv">styles</span><span class="p">.</span><span class="nv">container</span><span class="k">}}</span><span class="nt">&gt;</span> <span class="nt">&lt;Hello</span> <span class="err">@</span><span class="na">name=</span><span class="k">{{</span><span class="nv">this</span><span class="p">.</span><span class="nv">userName</span><span class="k">}}</span> <span class="err">&lt;/</span><span class="na">div</span><span class="nt">&gt;</span> </code></pre> </div> <p>We see that the controller provides styles and <code>userName</code>, a getter that returns some string.</p> <p>1. Change the file extension to <code>.gts</code>. Surround the template with the <code>&lt;template&gt;</code> tag.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-app: app/templates/index.gts */ <span class="gi">+ &lt;template&gt; </span> &lt;div class={{this.styles.container}}&gt; &lt;Hello @name={{this.userName}} &lt;/div&gt; <span class="gi">+ &lt;/template&gt; </span></code></pre> </div> <p>2. Enter strict mode. Instead of <code>this</code>, write <code>@controller</code> to indicate things from the controller. Just like before, <code>@model</code> refers to the <code>model</code> hook's return value.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-app: app/templates/index.gts */ <span class="gi">+ import { Hello } from 'my-addon'; + </span>&lt;template&gt; <span class="gd">- &lt;div class={{this.styles.container}}&gt; </span><span class="gi">+ &lt;div class={{@controller.styles.container}}&gt; </span><span class="gd">- &lt;Hello @name={{this.userName}} </span><span class="gi">+ &lt;Hello @name={{@controller.userName}} </span> &lt;/div&gt; &lt;/template&gt; </code></pre> </div> <p>3. The prior code is enough for <code>.gjs</code>, but not for <code>.gts</code>. If the template includes <code>@controller</code> or <code>@model</code>, provide the signature (their types).<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-app: app/templates/index.gts */ <span class="gi">+ import type { TOC } from '@ember/component/template-only'; </span><span class="p">import { Hello } from 'my-addon'; </span><span class="gi">+ import type IndexController from 'my-app/controllers/index'; + + interface IndexSignature { + Args: { + controller: IndexController; + model: unknown; + }; + } </span><span class="err"> </span>&lt;template&gt; &lt;div class={{@controller.styles.container}}&gt; &lt;Hello @name={{@controller.userName}} &lt;/div&gt; <span class="gd">- &lt;/template&gt; </span><span class="gi">+ &lt;/template&gt; satisfies TOC&lt;IndexSignature&gt;; </span></code></pre> </div> <p>4. (Optional) Remove unnecessary code. Here, we can colocate the stylesheet so that we rely less on the controller (with the aim of removing it).<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-app: app/templates/index.gts */ <span class="p">import type { TOC } from '@ember/component/template-only'; import { Hello } from 'my-addon'; import type IndexController from 'my-app/controllers/index'; </span><span class="gi">+ + import styles from './index.module.css'; </span><span class="err"> </span><span class="p">interface IndexSignature { </span> Args: { controller: IndexController; model: unknown; }; } <span class="err"> </span>&lt;template&gt; <span class="gd">- &lt;div class={{@controller.styles.container}}&gt; </span><span class="gi">+ &lt;div class={{styles.container}}&gt; </span> &lt;Hello @name={{@controller.userName}} &lt;/div&gt; &lt;/template&gt; satisfies TOC&lt;IndexSignature&gt;; </code></pre> </div> <p>We can even use a Glimmer component to remove states from the controller.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>/* my-app: app/templates/index.gts */ import Component from '@glimmer/component'; import { Hello } from 'my-addon'; import styles from './index.module.css'; interface IndexSignature { Args: { controller: unknown; model: unknown; }; } export default class IndexRoute extends Component&lt;IndexSignature&gt; { get userName(): string { return 'Zoey'; } &lt;template&gt; &lt;div class={{styles.container}}&gt; &lt;Hello @name={{this.userName}} &lt;/div&gt; &lt;/template&gt; } </code></pre> </div> <h3> c. Tests </h3> <p>Last but not least, let's update the test file for <code>&lt;Hello&gt;</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="cm">/* my-app: tests/integration/components/hello-test.ts */</span> <span class="k">import</span> <span class="p">{</span> <span class="nx">render</span><span class="p">,</span> <span class="kd">type</span> <span class="nx">TestContext</span> <span class="k">as</span> <span class="nx">BaseTestContext</span><span class="p">,</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">@ember/test-helpers</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="p">{</span> <span class="nx">hbs</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ember-cli-htmlbars</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="p">{</span> <span class="nx">setupRenderingTest</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">my-app/tests/helpers</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="p">{</span> <span class="kr">module</span><span class="p">,</span> <span class="nx">test</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">qunit</span><span class="dl">'</span><span class="p">;</span> <span class="kr">interface</span> <span class="nx">TestContext</span> <span class="kd">extends</span> <span class="nx">BaseTestContext</span> <span class="p">{</span> <span class="nl">userName</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="p">}</span> <span class="nf">module</span><span class="p">(</span><span class="dl">'</span><span class="s1">Integration | Component | hello</span><span class="dl">'</span><span class="p">,</span> <span class="nf">function </span><span class="p">(</span><span class="nx">hooks</span><span class="p">)</span> <span class="p">{</span> <span class="nf">setupRenderingTest</span><span class="p">(</span><span class="nx">hooks</span><span class="p">);</span> <span class="nx">hooks</span><span class="p">.</span><span class="nf">beforeEach</span><span class="p">(</span><span class="nf">function </span><span class="p">(</span><span class="k">this</span><span class="p">:</span> <span class="nx">TestContext</span><span class="p">)</span> <span class="p">{</span> <span class="k">this</span><span class="p">.</span><span class="nx">userName</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">Zoey</span><span class="dl">'</span><span class="p">;</span> <span class="p">});</span> <span class="nf">test</span><span class="p">(</span><span class="dl">'</span><span class="s1">it renders</span><span class="dl">'</span><span class="p">,</span> <span class="k">async</span> <span class="nf">function </span><span class="p">(</span><span class="k">this</span><span class="p">:</span> <span class="nx">TestContext</span><span class="p">,</span> <span class="nx">assert</span><span class="p">)</span> <span class="p">{</span> <span class="k">await</span> <span class="nx">render</span><span class="o">&lt;</span><span class="nx">TestContext</span><span class="o">&gt;</span><span class="p">(</span> <span class="nx">hbs</span><span class="s2">` &lt;Hello @name={{this.userName}} /&gt; `</span><span class="p">,</span> <span class="p">);</span> <span class="nx">assert</span><span class="p">.</span><span class="nf">dom</span><span class="p">().</span><span class="nf">hasText</span><span class="p">(</span><span class="dl">'</span><span class="s1">Hello, Zoey!</span><span class="dl">'</span><span class="p">);</span> <span class="p">});</span> <span class="p">});</span> </code></pre> </div> <p>1. Change the file extension, replace the <code>hbs</code> tags with <code>&lt;template&gt;</code>, then enter strict mode.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-app: tests/integration/components/hello-test.gts */ <span class="p">import { </span> render, type TestContext as BaseTestContext, } from '@ember/test-helpers'; <span class="gd">- import { hbs } from 'ember-cli-htmlbars'; </span><span class="gi">+ import { Hello } from 'my-addon'; </span><span class="p">import { setupRenderingTest } from 'my-app/tests/helpers'; import { module, test } from 'qunit'; </span><span class="err"> </span><span class="p">interface TestContext extends BaseTestContext { </span> userName: string; } <span class="err"> </span><span class="p">module('Integration | Component | hello', function (hooks) { </span> setupRenderingTest(hooks); <span class="err"> </span> hooks.beforeEach(function (this: TestContext) { this.userName = 'Zoey'; }); <span class="err"> </span> test('it renders', async function (this: TestContext, assert) { <span class="gd">- await render&lt;TestContext&gt;( </span><span class="gi">+ await render( </span><span class="gd">- hbs` </span><span class="gi">+ &lt;template&gt; </span> &lt;Hello @name={{this.userName}} /&gt; <span class="gd">- `, </span><span class="gi">+ &lt;/template&gt;, </span> ); <span class="err"> </span> assert.dom().hasText('Hello, Zoey!'); }); }); </code></pre> </div> <p>The template inside <code>render()</code> is in strict mode, so <code>glint</code> no longer needs an extra <code>TestContext</code> to analyze <code>render()</code>.</p> <p>2. You may have used QUnit's <code>beforeEach</code> hook to define things that will be passed to the template (for all tests of a module). Currently, a bug in Ember causes assertions to fail if we keep using <code>this</code> to pass things to the template.</p> <p>We can get around this issue (pun intended) in a few different ways. One is to create an alias of <code>this</code>, called <code>self</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-app: tests/integration/components/hello-test.gts */ <span class="p">import { </span> render, type TestContext as BaseTestContext, } from '@ember/test-helpers'; <span class="p">import { Hello } from 'my-addon'; import { setupRenderingTest } from 'my-app/tests/helpers'; import { module, test } from 'qunit'; </span><span class="err"> </span><span class="p">interface TestContext extends BaseTestContext { </span> userName: string; } <span class="err"> </span><span class="p">module('Integration | Component | hello', function (hooks) { </span> setupRenderingTest(hooks); <span class="err"> </span> hooks.beforeEach(function (this: TestContext) { this.userName = 'Zoey'; }); <span class="err"> </span> test('it renders', async function (this: TestContext, assert) { <span class="gi">+ const self = this; + </span> await render( &lt;template&gt; <span class="gd">- &lt;Hello @name={{this.userName}} /&gt; </span><span class="gi">+ &lt;Hello @name={{self.userName}} /&gt; </span> &lt;/template&gt;, ); <span class="err"> </span> assert.dom().hasText('Hello, Zoey!'); }); }); </code></pre> </div> <p>Another is to destructure <code>this</code> so that we can pass things as variables.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* my-app: tests/integration/components/hello-test.gts */ <span class="p">import { </span> render, type TestContext as BaseTestContext, } from '@ember/test-helpers'; <span class="p">import { Hello } from 'my-addon'; import { setupRenderingTest } from 'my-app/tests/helpers'; import { module, test } from 'qunit'; </span><span class="err"> </span><span class="p">interface TestContext extends BaseTestContext { </span> userName: string; } <span class="err"> </span><span class="p">module('Integration | Component | hello', function (hooks) { </span> setupRenderingTest(hooks); <span class="err"> </span> hooks.beforeEach(function (this: TestContext) { this.userName = 'Zoey'; }); <span class="err"> </span> test('it renders', async function (this: TestContext, assert) { <span class="gi">+ const { userName } = this; + </span> await render( &lt;template&gt; <span class="gd">- &lt;Hello @name={{this.userName}} /&gt; </span><span class="gi">+ &lt;Hello @name={{userName}} /&gt; </span> &lt;/template&gt;, ); <span class="err"> </span> assert.dom().hasText('Hello, Zoey!'); }); }); </code></pre> </div> <p>A third option is to define variables at a global level (scoped to a test module). By doing so, we may be able to remove <code>TestContext</code> altogether.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>/* my-app: tests/integration/components/hello-test.gts */ import { render } from '@ember/test-helpers'; import { Hello } from 'my-addon'; import { setupRenderingTest } from 'my-app/tests/helpers'; import { module, test } from 'qunit'; module('Integration | Component | hello', function (hooks) { setupRenderingTest(hooks); const userName = 'Zoey'; test('it renders', async function (assert) { await render( &lt;template&gt; &lt;Hello @name={{userName}} /&gt; &lt;/template&gt;, ); assert.dom().hasText('Hello, Zoey!'); }); }); </code></pre> </div> <p>Finally, to prevent misusing global variables, to customize test setups, or to facilitate the removal of dead code, you can define things locally instead.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>/* my-app: tests/integration/components/hello-test.gts */ import { render } from '@ember/test-helpers'; import { Hello } from 'my-addon'; import { setupRenderingTest } from 'my-app/tests/helpers'; import { module, test } from 'qunit'; module('Integration | Component | hello', function (hooks) { setupRenderingTest(hooks); test('it renders', async function (assert) { const userName = 'Zoey'; await render( &lt;template&gt; &lt;Hello @name={{userName}} /&gt; &lt;/template&gt;, ); assert.dom().hasText('Hello, Zoey!'); }); }); </code></pre> </div> <h2> 3. ember-codemod-add-template-tags </h2> <p>Time to automate. In <a href="https://crunchingnumbers.live/2025/09/22/large-scale-migrations-with-codemods/" rel="noopener noreferrer">an earlier post</a>, I revealed a codemod that performs static code analysis and supports apps, addons, and monorepos.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code><span class="c"># From the workspace or package root</span> pnpx ember-codemod-add-template-tags </code></pre> </div> <p>In case you'd like to incrementally migrate, the codemod also provides the options <code>--convert</code> and <code>--folder</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code><span class="c"># Components and tests only</span> pnpx ember-codemod-add-template-tags <span class="nt">--convert</span> components tests <span class="c"># `ui/form` folder only</span> pnpx ember-codemod-add-template-tags <span class="nt">--convert</span> components tests <span class="nt">--folder</span> ui/form </code></pre> </div> <p>Did you guess? The codemod performs the exact steps that you learned above.</p> ember javascript opensource webdev Isaac Lee Sat, 14 Jun 2025 06:15:15 +0000 https://dev.to/ijlee2/its-time-to-separate-lint-and-test-376b https://dev.to/ijlee2/its-time-to-separate-lint-and-test-376b <p>Today, you get to learn a pet peeve of mine, a rare instance where I never follow what Ember blueprints say since 2020.</p> <p>Since <a href="https://github.com/ember-cli/ember-cli/blob/v3.17.0/blueprints/app/files/package.json#L19" rel="noopener noreferrer">version 3.17.0</a>, <code>ember-cli</code> generates apps and addons with a test script that—weirdly—checks files for lint and format errors.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight json"><code><span class="err">/*</span><span class="w"> </span><span class="err">package.json</span><span class="w"> </span><span class="err">(generated</span><span class="w"> </span><span class="err">by</span><span class="w"> </span><span class="err">ember-cli@</span><span class="mf">6.4</span><span class="err">.</span><span class="mi">0</span><span class="err">)</span><span class="w"> </span><span class="err">*/</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"scripts"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"build"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ember build --environment=production"</span><span class="p">,</span><span class="w"> </span><span class="nl">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"prettier . --cache --write"</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint"</span><span class="p">:</span><span class="w"> </span><span class="s2">"concurrently </span><span class="se">\"</span><span class="s2">pnpm:lint:*(!fix)</span><span class="se">\"</span><span class="s2"> --names </span><span class="se">\"</span><span class="s2">lint:</span><span class="se">\"</span><span class="s2"> --prefixColors auto"</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint:css"</span><span class="p">:</span><span class="w"> </span><span class="s2">"stylelint </span><span class="se">\"</span><span class="s2">**/*.css</span><span class="se">\"</span><span class="s2">"</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint:css:fix"</span><span class="p">:</span><span class="w"> </span><span class="s2">"concurrently </span><span class="se">\"</span><span class="s2">pnpm:lint:css -- --fix</span><span class="se">\"</span><span class="s2">"</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint:fix"</span><span class="p">:</span><span class="w"> </span><span class="s2">"concurrently </span><span class="se">\"</span><span class="s2">pnpm:lint:*:fix</span><span class="se">\"</span><span class="s2"> --names </span><span class="se">\"</span><span class="s2">fix:</span><span class="se">\"</span><span class="s2"> --prefixColors auto &amp;&amp; pnpm format"</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint:format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"prettier . --cache --check"</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint:hbs"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ember-template-lint ."</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint:hbs:fix"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ember-template-lint . --fix"</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint:js"</span><span class="p">:</span><span class="w"> </span><span class="s2">"eslint . --cache"</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint:js:fix"</span><span class="p">:</span><span class="w"> </span><span class="s2">"eslint . --fix"</span><span class="p">,</span><span class="w"> </span><span class="nl">"lint:types"</span><span class="p">:</span><span class="w"> </span><span class="s2">"tsc --noEmit"</span><span class="p">,</span><span class="w"> </span><span class="nl">"test"</span><span class="p">:</span><span class="w"> </span><span class="s2">"concurrently </span><span class="se">\"</span><span class="s2">pnpm:lint</span><span class="se">\"</span><span class="s2"> </span><span class="se">\"</span><span class="s2">pnpm:test:*</span><span class="se">\"</span><span class="s2"> --names </span><span class="se">\"</span><span class="s2">lint,test:</span><span class="se">\"</span><span class="s2"> --prefixColors auto"</span><span class="p">,</span><span class="w"> </span><span class="nl">"test:ember"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ember test"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre> </div> <p>The lack of separation between lint and test resulted in 3 side effects that the <a href="https://github.com/ember-cli/ember-cli/pull/9009" rel="noopener noreferrer">initial implementation hadn't accounted for</a>:</p> <ul> <li>In CI, <a href="https://github.com/ember-cli/ember-cli/blob/v6.4.0/blueprints/app/files/.github/workflows/ci.yml#L52-L53" rel="noopener noreferrer">the lint command runs twice</a>.</li> <li>In <a href="https://github.com/ember-cli/ember-cli/blob/v6.4.0/blueprints/app/files/README.md?plain=1#L33-L36" rel="noopener noreferrer"><code>README</code></a> and <a href="https://github.com/ember-cli/ember-cli/blob/v6.4.0/blueprints/addon/files/CONTRIBUTING.md?plain=1#L16-L17" rel="noopener noreferrer"><code>CONTRIBUTING</code></a>, the test commands show an incongruence: People can run <code>pnpm test</code> and <code>pnpm test:ember --server</code>. Wouldn't <code>pnpm test --server</code> make more sense?¹ They neglect to mention that the <code>test</code> command lints files, which has occasionally led to questions on Ember Discord.</li> <li>We need to add the query parameter <code>nolint</code> to the <code>/tests</code> URL, if we don't want lint results from addons to double the test report size. This issue was prevalent when we had depended on <a href="https://github.com/ember-cli/ember-cli-eslint" rel="noopener noreferrer">ember-cli-eslint</a> and <a href="https://github.com/ember-template-lint/ember-cli-template-lint" rel="noopener noreferrer">ember-cli-template-lint</a>. We can still get a mixed report due to <a href="https://github.com/salsify/ember-cli-dependency-lint" rel="noopener noreferrer">ember-cli-dependency-lint</a>.</li> </ul> <p>The fix is simple:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>{ "scripts": { <span class="gd">- "test": "concurrently \"pnpm:lint\" \"pnpm:test:*\" --names \"lint,test:\" --prefixColors auto", - "test:ember": "ember test" </span><span class="gi">+ "test": "ember test" </span> } } </code></pre> </div> <p>In v1 addons, and in <a href="https://github.com/ijlee2/embroider-toolbox/blob/1.2.0/packages/create-v2-addon-repo/src/blueprints/test-app/package.json#L27-L28" rel="noopener noreferrer">apps that test v2 addons</a>, I use these scripts:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight json"><code><span class="p">{</span><span class="w"> </span><span class="nl">"scripts"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"test"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ember test"</span><span class="p">,</span><span class="w"> </span><span class="nl">"test:ember-compatibility"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ember try:one"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre> </div> <p>Note, the test script for <a href="https://github.com/ember-cli/ember-try" rel="noopener noreferrer">ember-try</a> uses <code>try:one</code> to run a single scenario, instead of <code>try:each</code> to run all. This way, we can <a href="https://github.com/ijlee2/embroider-toolbox/blob/1.2.0/packages/create-v2-addon-repo/src/blueprints/.github/workflows/ci.yml#L117-L127" rel="noopener noreferrer">run our scenarios in CI in parallel</a>, and locally test a failing scenario quickly. Separation FTW.</p> <p>While I could continue to apply these changes to my projects manually, it'd be better if we update the blueprints to reflect the Ember ecosystem of now and our improved knowledge of CI since 2020.</p> <p>There isn't yet an <a href="https://github.com/emberjs/rfcs" rel="noopener noreferrer">RFC</a> that highlights the issues above and <a href="https://github.com/ember-cli/ember-cli/pull/10663" rel="noopener noreferrer">proposes change</a>. I think this is because we've gotten used to the problems and think less over time in the shoes of a newcomer. Let's make Ember projects a delight to work with.</p> <h2> Notes </h2> <ol> <li>You will get an error when you run <code>pnpm test --server</code>. The error message says: <code>Unknown option: 'server'</code>. Unknown to whom? <code>pnpm</code>, <code>concurrently</code>, <code>pnpm:lint</code>, or <code>pnpm:test:*</code>?</li> </ol> ember javascript testing beginners Isaac Lee Mon, 02 Jun 2025 11:54:22 +0000 https://dev.to/ijlee2/its-time-to-separate-lint-and-format-1oef https://dev.to/ijlee2/its-time-to-separate-lint-and-format-1oef <p>In the It's Time to Separate series, I'll show you how separating concerns helps us simplify code. And that separation can occur in many places.</p> <p>Little advertised news from January: Ember CLI removed <a href="https://github.com/prettier/eslint-plugin-prettier" rel="noopener noreferrer">eslint-plugin-prettier</a> and <a href="https://github.com/prettier/stylelint-prettier" rel="noopener noreferrer">stylelint-prettier</a> from its blueprints, <a href="https://github.com/ember-cli/ember-cli/pull/10596" rel="noopener noreferrer">adding instead two scripts</a> to run <code>prettier</code>. I was skeptical when the <a href="https://github.com/emberjs/rfcs/blob/master/text/1055-vanilla-prettier-setup-in-blueprints.md" rel="noopener noreferrer">RFC</a> had come out. Why change things when these plugins have worked well for years? Isn't it, for people who maintain many projects like me, huge effort, little reward?</p> <p>Then I realized last week, separating formatting from linting is indeed a good thing. Not just cause of the performance gain that's usually cited. But because it helps us reexamine past approaches and come up with simpler ones that will stand the test of time.</p> <h2> 1. How to migrate </h2> <p>Separation was painless. You could run <a href="https://github.com/ember-cli/ember-cli-update" rel="noopener noreferrer">ember-cli-update</a> (<a href="https://blog.emberjs.com/ember-released-6-3" rel="noopener noreferrer">set the version to 6.3.0</a> or higher). But likely you can't cause you have Ember v5 or less, and didn't address <a href="https://deprecations.emberjs.com/v5.x" rel="noopener noreferrer">all the deprecations</a>.</p> <p>You don't need to. <em>Separate</em> the Prettier migration from the Ember update. Here are the steps, assuming that your project didn't deviate much from the blueprints. If you get lost, you can look at <a href="https://github.com/ijlee2/frontend-configs" rel="noopener noreferrer">my open-sourced configs</a>.</p> <p>1. In <code>package.json</code>, remove <code>eslint-plugin-prettier</code> and <code>stylelint-prettier</code>. Update the scripts to separate formatting and linting.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* package.json */ { "scripts": { <span class="gi">+ "format": "prettier . --cache --write", </span> "lint": "concurrently \"pnpm:lint:*(!fix)\" --names \"lint:\"", "lint:css": "stylelint \"**/*.css\" --cache", "lint:css:fix": "pnpm lint:css --fix", <span class="gd">- "lint:fix": "concurrently \"pnpm:lint:*:fix\" --names \"fix:\"", </span><span class="gi">+ "lint:fix": "concurrently \"pnpm:lint:*:fix\" --names \"fix:\" &amp;&amp; pnpm format", + "lint:format": "prettier . --cache --check", </span> "lint:js": "eslint . --cache", "lint:js:fix": "pnpm lint:js --fix" }, "devDependencies": { "concurrently": "...", "eslint": "...", "eslint-config-prettier": "...", <span class="gd">- "eslint-plugin-prettier": "...", </span> "prettier": "...", "prettier-plugin-ember-template-tag": "..." "stylelint": "...", <span class="gd">- "stylelint-prettier": "..." </span> } } </code></pre> </div> <p>If you have <a href="https://crunchingnumbers.live/2025/02/11/shared-lint-configs/" rel="noopener noreferrer">shared configurations</a> for <code>eslint</code> and <code>stylelint</code>, you can remove <code>prettier</code> from peer dependencies.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* package.json (eslint config) */ { "peerDependencies": { "eslint": "^9.0.0", <span class="gd">- "prettier": "^3.0.0", </span> "typescript": "^5.0.0" }, "peerDependenciesMeta": { "typescript": { "optional": true } } } </code></pre> </div> <p>2. Remove <code>eslint-plugin-prettier</code> from the <code>eslint</code> configuration.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* eslint.config.mjs (eslint@v9) */ <span class="p">import eslint from '@eslint/js'; </span><span class="gd">- import eslintPluginPrettier from 'eslint-plugin-prettier/recommended'; </span><span class="gi">+ import eslintConfigPrettier from 'eslint-config-prettier'; </span><span class="p">import tseslint from 'typescript-eslint'; </span><span class="err"> </span><span class="p">export default tseslint.config( </span> eslint.configs.recommended, <span class="gd">- eslintPluginPrettier, </span><span class="gi">+ eslintConfigPrettier, </span>); </code></pre> </div> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* .eslintrc.cjs (eslint@v8) */ 'use strict'; <span class="err"> </span><span class="p">module.exports = { </span> extends: [ 'eslint:recommended', <span class="gd">- 'plugin:prettier/recommended', </span><span class="gi">+ 'prettier', </span> ], }; </code></pre> </div> <p>Note, we added <code>eslint-config-prettier</code> to turn off <code>eslint</code> rules that may conflict with <code>prettier</code>. <code>eslint-plugin-prettier</code> used to do this for us.</p> <p>Also worth knowing, <code>eslint-plugin-prettier</code> had to be the last plugin in order to override rules from the preceding ones. You'll be fine if you list <code>eslint-config-prettier</code> where <code>eslint-plugin-prettier</code> used to be.</p> <p>3. Remove <code>stylelint-prettier</code> from the <code>stylelint</code> configuration.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* .stylelintrc.mjs */ <span class="p">export default { </span><span class="gd">- extends: ['stylelint-config-standard', 'stylelint-prettier/recommended'], </span><span class="gi">+ extends: ['stylelint-config-standard'], </span>}; </code></pre> </div> <p>4. Run <code>install</code> to update your dependencies. Run <code>lint:css</code> and <code>lint:js</code> to check that files can be linted.</p> <p>5. Prettier now checks more files than it used to via linter plugins. Run <code>lint:format</code> to identify files that shouldn't be formatted. List them in <code>.prettierignore</code>. Here is the starter config for Ember apps:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code># unconventional js /blueprints/*/files/ # compiled output /dist/ # misc /coverage/ !.* .*/ *.html pnpm-lock.yaml # specific to my package ... </code></pre> </div> <p>Note, <code>*.html</code> was added as a temporary fix for <a href="https://github.com/prettier/prettier/issues/15336" rel="noopener noreferrer">a bug in Prettier</a>. <code>pnpm-lock.yaml</code> isn't needed if the package is a workspace in a monorepo.</p> <p>Migration complete! What's nice about the names <code>format</code> and <code>lint:format</code> is backward compatibility. Just like before, developers need to know only 3 scripts to review their work:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code><span class="c"># Check errors</span> pnpm lint <span class="c"># Fix errors</span> pnpm lint:fix <span class="c"># Run tests</span> pnpm <span class="nb">test</span> </code></pre> </div> <h2> 2. How to format hbs </h2> <p>Ember aficionados may notice a gap. What about Glimmer templates?</p> <p>Until now, we had to use <a href="https://github.com/ember-template-lint/ember-template-lint-plugin-prettier" rel="noopener noreferrer">ember-template-lint-plugin-prettier</a> to format <code>*.hbs</code> files. This is a bit strange, because <a href="https://dev.toPrettier%20natively%20supports%20Handlebars">Prettier natively supports Handlebars</a> since May 2021.</p> <p>The plugin also comes with a few issues:</p> <ul> <li>It uglifies code inside an <code>hbs</code> tag (i.e. wrong indentations in rendering tests, Storybook stories).</li> <li>It needs to dynamically load <code>prettier</code> and use a hook from <code>ember-template-lint</code> to format <code>*.hbs</code>. Due to strong coupling, it will fall behind if <code>prettier</code> or <code>ember-template-lint</code> makes a breaking change to their API.</li> <li>Prettier recommends not running prettier through a linter plugin. Partly why Ember CLI removed the <code>eslint</code> and <code>stylelint</code> plugins.</li> </ul> <p>Thanks to the separation, we can see that all we need now is a Prettier plugin that formats hbs tags.</p> <p>Enter <a href="https://github.com/ijlee2/prettier-plugin-ember-hbs-tag" rel="noopener noreferrer">prettier-plugin-ember-hbs-tag</a>, a plugin that I wrote last week. Just like <a href="https://github.com/ember-tooling/prettier-plugin-ember-template-tag" rel="noopener noreferrer">prettier-plugin-ember-template-tag</a>, it has one job and doesn't need a linter to run. Here is the starter config:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="cm">/* prettier.config.mjs */</span> <span class="k">export</span> <span class="k">default</span> <span class="p">{</span> <span class="na">plugins</span><span class="p">:</span> <span class="p">[</span> <span class="dl">'</span><span class="s1">prettier-plugin-ember-hbs-tag</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">prettier-plugin-ember-template-tag</span><span class="dl">'</span><span class="p">,</span> <span class="p">],</span> <span class="na">overrides</span><span class="p">:</span> <span class="p">[</span> <span class="p">{</span> <span class="na">files</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">*.{cjs,cts,js,mjs,mts,ts}</span><span class="dl">'</span><span class="p">],</span> <span class="na">options</span><span class="p">:</span> <span class="p">{</span> <span class="na">singleQuote</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="p">},</span> <span class="p">},</span> <span class="p">{</span> <span class="na">files</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">tests/**/*-test.{js,ts}</span><span class="dl">'</span><span class="p">],</span> <span class="na">options</span><span class="p">:</span> <span class="p">{</span> <span class="na">parser</span><span class="p">:</span> <span class="dl">'</span><span class="s1">ember-hbs-tag</span><span class="dl">'</span><span class="p">,</span> <span class="na">singleQuote</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="na">templateSingleQuote</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span> <span class="p">},</span> <span class="p">},</span> <span class="p">{</span> <span class="na">files</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">*.{gjs,gts}</span><span class="dl">'</span><span class="p">],</span> <span class="na">options</span><span class="p">:</span> <span class="p">{</span> <span class="na">singleQuote</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="na">templateSingleQuote</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span> <span class="p">},</span> <span class="p">},</span> <span class="p">{</span> <span class="na">files</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">*.hbs</span><span class="dl">'</span><span class="p">],</span> <span class="na">options</span><span class="p">:</span> <span class="p">{</span> <span class="na">printWidth</span><span class="p">:</span> <span class="mi">64</span><span class="p">,</span> <span class="na">singleQuote</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span> <span class="p">},</span> <span class="p">},</span> <span class="p">],</span> <span class="p">};</span> </code></pre> </div> <p>Then, remove <code>ember-template-lint-plugin-prettier</code> from the <code>ember-template-lint</code> config and uninstall the package:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* .template-lintrc.cjs */ 'use strict'; <span class="err"> </span><span class="p">module.exports = { </span><span class="gd">- plugins: ['ember-template-lint-plugin-prettier'], - extends: ['recommended', 'ember-template-lint-plugin-prettier:recommended'], - overrides: [ - { - files: ['**/*.{gjs,gts}'], - rules: { - prettier: 'off', - }, - }, - { - files: ['tests/**/*-test.{js,ts}'], - rules: { - prettier: 'off', - }, - }, - ], </span><span class="gi">+ extends: ['recommended'], </span>}; </code></pre> </div> <div class="highlight js-code-highlight"> <pre class="highlight diff"><code>/* package.json */ { "devDependencies": { "ember-template-lint": "...", <span class="gd">- "ember-template-lint-plugin-prettier": "...", </span> "prettier": "...", <span class="gi">+ "prettier-plugin-ember-hbs-tag": "...", </span> "prettier-plugin-ember-template-tag": "..." } } </code></pre> </div> <p>With that, you can format <em>everything</em>. <a href="https://github.com/ijlee2/prettier-plugin-ember-hbs-tag" rel="noopener noreferrer">Don't forget to star</a>. ✨</p> <h2> 3. Even more separation </h2> <p>Starting with <code>ember-template-lint@7.7.0</code>, you can <a href="https://github.com/ijlee2/ember-codemod-sort-invocations" rel="noopener noreferrer">sort invocations</a>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="cm">/* .template-lintrc.cjs */</span> <span class="dl">'</span><span class="s1">use strict</span><span class="dl">'</span><span class="p">;</span> <span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="p">{</span> <span class="na">extends</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">recommended</span><span class="dl">'</span><span class="p">],</span> <span class="na">rules</span><span class="p">:</span> <span class="p">{</span> <span class="dl">'</span><span class="s1">sort-invocations</span><span class="dl">'</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="p">},</span> <span class="p">};</span> </code></pre> </div> <p>In order to fix a long-standing issue, <code>sort-invocations</code> leaves formatting up to the two Prettier plugins. Stay tuned for the dedicated post.</p> ember prettier javascript opensource Isaac Lee Fri, 19 Jul 2024 09:28:47 +0000 https://dev.to/ijlee2/fixing-package-dependencies-5557 https://dev.to/ijlee2/fixing-package-dependencies-5557 <p>Both <a href="https://github.com/embroider-build/embroider" rel="noopener noreferrer">Embroider</a> and <code>pnpm</code> ask that packages declare their dependencies correctly: List a dependency (if and only) if it is used.</p> <p>This is difficult to do when working on a large monorepo (consider an Ember app with many Ember addons and Node packages) that uses <code>yarn@v1</code>. Developers can forget to update the <code>package.json</code>'s, because the Ember app can build and run even when a dependency is missing, as long as it gets pulled in from another package.</p> <p>So neither build nor run can tell us if some package didn't declare its dependencies right. How else can we fix the <code>package.json</code>'s so that we can introduce Embroider and <code>pnpm</code>?</p> <h2> 1. Static code analysis </h2> <p>Given a file, we can see which dependencies should be present, because we know how JavaScript and Ember work.</p> <p>For example, were a JavaScript (or TypeScript) file to show,<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="k">import</span> <span class="p">{</span> <span class="nx">setupIntl</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ember-intl/test-support</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="p">{</span> <span class="nx">setupRenderingTest</span> <span class="k">as</span> <span class="nx">upstreamSetupRenderingTest</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ember-qunit</span><span class="dl">'</span><span class="p">;</span> <span class="k">export</span> <span class="kd">function</span> <span class="nf">setupRenderingTest</span><span class="p">(</span><span class="nx">hooks</span><span class="p">,</span> <span class="nx">options</span><span class="p">)</span> <span class="p">{</span> <span class="nf">upstreamSetupRenderingTest</span><span class="p">(</span><span class="nx">hooks</span><span class="p">,</span> <span class="nx">options</span><span class="p">);</span> <span class="c1">// Additional setup for rendering tests can be done here.</span> <span class="nf">setupIntl</span><span class="p">(</span><span class="nx">hooks</span><span class="p">,</span> <span class="dl">'</span><span class="s1">de-de</span><span class="dl">'</span><span class="p">);</span> <span class="p">}</span> </code></pre> </div> <p>we would tell from the import statements that the package depends on <code>ember-intl</code> and <code>ember-qunit</code>.</p> <p>And, if a template file were to show,<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight handlebars"><code><span class="k">{{</span><span class="nv">page-title</span> <span class="s2">"My App"</span><span class="k">}}</span> <span class="nt">&lt;WelcomePage</span> <span class="nt">/&gt;</span> <span class="k">{{</span><span class="nv">outlet</span><span class="k">}}</span> </code></pre> </div> <p>our knowledge of Ember and its addon ecosystem would direct us to <code>ember-page-title</code>, <code>ember-welcome-page</code>, and <code>ember-source</code>, respectively.</p> <p>Even when things are implicit (e.g. ambiguity in double curly braces, module resolution, service injection), we can guess the origin of an entity (entities are components, helpers, modifiers, services, etc.) with high accuracy, thanks to Ember's strong conventions.</p> <h2> 2. Codemod </h2> <p>Still, we shouldn't check every file in every package manually. That's time-consuming and error-prone.</p> <p>Instead, we write a codemod (really, a linter) using <a href="https://github.com/ijlee2/codemod-utils" rel="noopener noreferrer"><code>@codemod-utils</code></a>. For every package, the codemod parses what's relevant and creates a list of dependencies that should be present ("actual"). It then compares the list to that from <code>package.json</code> ("expected").</p> <p>To analyze implicit code, there needs to be a list of known entities (a one-time creation), which maps every package that we want to consider to its entities. We can use a <code>Map</code> to record that information.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="kd">const</span> <span class="nx">KNOWN_ENTITIES</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">Map</span><span class="p">([</span> <span class="p">[</span> <span class="dl">'</span><span class="s1">ember-intl</span><span class="dl">'</span><span class="p">,</span> <span class="p">{</span> <span class="na">helpers</span><span class="p">:</span> <span class="p">[</span> <span class="dl">'</span><span class="s1">format-date</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">format-list</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">format-message</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">format-number</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">format-relative</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">format-time</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">t</span><span class="dl">'</span><span class="p">,</span> <span class="p">],</span> <span class="na">services</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">intl</span><span class="dl">'</span><span class="p">],</span> <span class="p">},</span> <span class="p">],</span> <span class="p">[</span> <span class="dl">'</span><span class="s1">ember-page-title</span><span class="dl">'</span><span class="p">,</span> <span class="p">{</span> <span class="na">helpers</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">page-title</span><span class="dl">'</span><span class="p">],</span> <span class="na">services</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">page-title</span><span class="dl">'</span><span class="p">],</span> <span class="p">},</span> <span class="p">],</span> <span class="p">[</span> <span class="dl">'</span><span class="s1">ember-welcome-page</span><span class="dl">'</span><span class="p">,</span> <span class="p">{</span> <span class="na">components</span><span class="p">:</span> <span class="p">[</span><span class="dl">'</span><span class="s1">welcome-page</span><span class="dl">'</span><span class="p">],</span> <span class="p">},</span> <span class="p">],</span> <span class="p">]);</span> </code></pre> </div> <p>Even explicit code like import statements aren't trivial to analyze. Take the following example:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="k">import</span> <span class="nx">Route</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">@ember/routing/route</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="nx">fetch</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">fetch</span><span class="dl">'</span><span class="p">;</span> </code></pre> </div> <p>When we don't provide the right context (i.e. this code is for Ember), the codemod would consider <code>@ember/routing</code> and <code>fetch</code> as dependencies, instead of <code>ember-source</code> and (likely) <code>ember-fetch</code>. The codemod should present its analysis in such a way that we can easily check for false positives and false negatives.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>// Results for my-package-37 { missingDependencies: [ 'ember-asset-loader', 'ember-truth-helpers' ], unusedDependencies: [ '@babel/core', 'ember-auto-import', 'ember-cli-babel' ], unknowns: [ 'Service - host-router (addon/routes/registration.ts)', ] } </code></pre> </div> <h2> 3. Results </h2> <p>The codemod that I had built (in a couple of days) analyzed a production repo with 123 packages in 25 seconds. There were a total of 11,108 files, but the codemod knew to analyze only 5,506 of them (less than half). That's an average of 0.005 seconds/file and 0.20 seconds/package!</p> <p>To learn more about writing codemods, check out the main tutorial from <a href="https://github.com/ijlee2/codemod-utils" rel="noopener noreferrer"><code>@codemod-utils</code></a>.</p> ember javascript showdev opensource Isaac Lee Thu, 20 Jul 2023 22:08:56 +0000 https://dev.to/ijlee2/in-1-year-25h0 https://dev.to/ijlee2/in-1-year-25h0 <p>Today, I'm going to show you how to create a platform so that you and your team can write code that is more maintainable and extensible.</p> <p>Since last year, at CLARK, we've been reducing our tech debt. Our main application is a monorepo with 190 packages, accrued over 7 or 8 years. We've been on Ember 3.28 for almost 2 years now. Trying to get to 4 hasn't been easy.</p> <p>These issues may sound familiar to you and I think it's a good thing to know that we don't have to face them alone. The <a href="https://emberjs.com/survey/2022/#s03-at-work" rel="noopener noreferrer">Ember Community Survey in 2022</a> estimated that 3 out of 4 work projects may be stuck on v3 or below. A follow-up survey in December indicated the lack of resource and outdated addons as main reasons.</p> <p>The question is, why are we finding ourselves in projects that are hard to maintain and extend? What can we do differently? I want to highlight possible solutions and give practical tips based on what my colleagues and I achieved over the last year.</p> <p>Keep in mind that the problems that I will describe are not specific to work or Ember v3, but more programming in general. The reason is, I want you to be able to apply these solutions in other contexts, e.g. in open-source projects like <a href="https://github.com/adopted-ember-addons" rel="noopener noreferrer">adopted-ember-addons</a> or when it's time to update Ember from 4 to 5.</p> <p>So, fangen wir mal an. Let's get started.</p> <h2> 1. In increments </h2> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F03.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F03.png" alt=""></a></p> <p>When you have to update a project that hasn't been maintained, you're going to feel, at first, overwhelmed, hopeless. How in the world do we get out of this mess? The key to doing so—and this is the most important lesson from my talk: Do it <em>in increments</em>.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2F0uegr9s5qicqb3x61civ.gif" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2F0uegr9s5qicqb3x61civ.gif" alt="A yarn is shown to be gradually untangled"></a></p> <p>Imagine a yarn that is wildly tangled up. The yarn is supposed to be just 1 simple thread, but it is a chaos and you can't tell where it starts and where it ends. Now, if you try to untangle the yarn by applying force in every direction, all at once, you're going to fail and make a bigger mess. But, if you give small little tugs, one at a time, sooner or later you'll find yourself that 1 simple thread.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F08.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F08.png" alt="4 contours, 3 consecutive arrows, and a target to illustrate how iterative methods work."></a></p> <p>This incremental approach is also what mathematicians favor. Global algorithms like finding the inverse of a function work well in theory but are very limited in practice. <a href="https://en.wikipedia.org/wiki/Iterative_method" rel="noopener noreferrer">Iterative methods</a>, on the other hand—taking a step in one direction, a step in another, and so on, until we converge to the right solution—are powerful because we can apply them to many different situations. They are also efficient and will end up saving us time.</p> <p>So what does an incremental approach mean for us developers? It means two things.</p> <p>First, when it's time to update a project, we have to avoid creating a plan that spans weeks or months. We also have to avoid planning down to the smallest detail. Now, I'm not saying, have no plan and just wing it. What I'm pointing out is that your code is alive. It will never stay still because someone on your team will add a feature, or some package that you depend on will have a release. The assumptions for how to update your project will change quickly, and you will have to adapt quickly as well.</p> <p>Second, an incremental approach means allowing mistakes. The right solution won't be obvious from the start, especially because the project hasn't been maintained. A pull request to update the project may introduce bugs, but that's okay, we can fix them in the next one. This may sound obvious but, if we take <em>no</em> steps because we fear of breaking the app, then we will get nowhere. Only by taking small steps and iterating on the solution can we make impossible possible.</p> <h3> 1a. Code metrics </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F09.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F09.png" alt=""></a></p> <p><em>You rated me a six. I was like, "Damn."</em></p> <p>The rest of my talk is devoted to showing which small steps you can take. But, before I do that, I'll share my thoughts on code metrics: <em>Should</em> we measure the improvements that we make?</p> <p>In math, a <a href="https://en.wikipedia.org/wiki/Metric_space" rel="noopener noreferrer">metric</a> is a number that describes a phenomenon without bias. For example, you are 10 centimeters taller than I, or the train was late by 5 minutes. One day, programmers, inspired by math, came up with numbers to describe <a href="https://en.wikipedia.org/wiki/Software_metric" rel="noopener noreferrer">code quality</a>. How many lines of code are there? How many components and routes do we have? And so on.</p> <p>The problem is, your code is alive and the assumptions for your project change from one day to another. You have to somehow ignore the changes that weren't in your control by normalizing the metric. Maybe divide the metric by the number of lines of code, or divide by the square root or the logarithm. Whatever you can think of.</p> <p>You're starting to see that we're fidgeting numbers and adding personal bias, when a metric is supposed to be objective. I claim that it's impossible to measure the <em>change</em> of a code metric—in other words, how much the code improved over time. We can only measure what is now, at this moment.</p> <p>Long story short, don't worry about code metrics. Just do the right thing and improve that code that you've wanted to.</p> <h2> 2. The right code </h2> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F10.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F10.png" alt=""></a></p> <p>The next question is, well, what is the right thing? What does it look like? The answer is going to depend on which aspects of code we care about. To help narrow the answer, we will focus on two: maintainability and extensibility.</p> <p>A code that we can maintain and extend exhibits 3 characteristics: It has a minimum API, it separates concerns, and it has few dependencies. In math, we say that these are <a href="https://en.wikipedia.org/wiki/Necessity_and_sufficiency" rel="noopener noreferrer">necessary conditions</a>. This means, if your code doesn't meet one of these conditions, it cannot be maintained or extended. Think of these as a checklist, where each item tells you which small steps you can take.</p> <p>To make things more concrete, I will use <a href="https://guides.emberjs.com/release/components/introducing-components" rel="noopener noreferrer">reusable components</a>, something that we are familiar with and use on a daily basis.</p> <h3> 2a. The right code has minimum API </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F12.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F12.png" alt=""></a></p> <p>An <a href="https://en.wikipedia.org/wiki/API" rel="noopener noreferrer">API</a> (application programming interface) defines a boundary between two code and rules for communicating with each other. When the interface is good, the code is easy to use, maintain, and extend. When the interface is bad, the code becomes a hazard and can stop your project at some point.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F13.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F13.png" alt="Two rectangles that represent the consumer and the reusable component. The rectangles are connected by a double-pointed arrow, which represents the API."></a></p> <p>A common mistake that I see in reusable components is supporting too many cases. That is, the component ended up with a large API by allowing many <a href="https://guides.emberjs.com/release/components/component-arguments-and-html-attributes" rel="noopener noreferrer">arguments</a>. This happens when we try to predict the future and overdesign things, or when we try to quickly fix something with an <code>if</code>-statement (if there is this new argument, I'm gonna do something else).</p> <p>What we tend to ignore is how every case increases <a href="https://en.wikipedia.org/wiki/Programming_complexity" rel="noopener noreferrer">complexity</a>. Not linearly but, I claim, quadratically or worse because of the <a href="https://en.wikipedia.org/wiki/Combinatorics" rel="noopener noreferrer">combinatorial</a> effect—how arguments interact with one another. We can assume that the higher the complexity, the more likely that the component is untested and unmaintained.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F14.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F14.png" alt="A humorous, fictitious photo of eierlegende Wollmilchsau, a hybrid animal with body parts from a chicken, sheep, cow, and pig."></a></p> <p>Back in Germany, we have this amazing animal that's going to sustain the future, called <a href="https://de.wikipedia.org/wiki/Eierlegende_Wollmilchsau" rel="noopener noreferrer">eierlegende Wollmilchsau</a>. It can give us eggs, wool, milk, meat, <em>and</em> companionship. It can do everything that we want, because it does not exist. It's an idiom like "Jack of all trades, master of none."</p> <p>So the lesson is, design simple things. Got it. But what if I already have a component with a large API? How do I simplify it?</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F15.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F15.png" alt=""></a></p> <p>The key to answering this question is researching your current use cases. Find out which features were almost always used and which maybe once or twice. The code for the rarely used features? See if you can delete them.</p> <p>By doing so, you reduce complexity and the chance that your component will cause an issue. Also, by removing code, you can cause a chain reaction of additional refactors. Remember, the way to untangle a yarn is to give small little tugs.</p> <p>Now, what if a feature was used once, but you have to support it? I'd create another component, maybe through composition. The idea is, to treat this feature as an exception and not the norm. When designing reusable components, I want you to <a href="https://en.wikipedia.org/wiki/Pareto_principle" rel="noopener noreferrer">target the 80%</a> and not give in to the other 20%.</p> <h3> 2b. The right code separates concerns </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F16.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F16.png" alt=""></a></p> <p>Recall that an API draws a boundary between two code. In the best case, each side trusts the other to perform only certain tasks and no others. When this happens, the tests for each side are simpler.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F17.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F17.png" alt="Two rectangles that represent the consumer and the reusable component. The rectangles are connected by a double-pointed arrow, which represents the API."></a></p> <p>The question is, when we design a reusable component, how should we separate responsibilities? Which tasks belong to the reusable component and which to the consumer, whether that's a component or route?</p> <p><a href="https://github.com/ijlee2/ember-workshop" rel="noopener noreferrer">In my experience</a>, we can maintain and extend the reusable component when it handles these 3 aspects:</p> <ul> <li> <a href="https://emberjs-1.gitbook.io/ember-component-patterns" rel="noopener noreferrer">Accessibility</a> (so the consumer doesn't have to be an expert in it)</li> <li>Styling (making sure that things inside the container look right)</li> <li> <a href="https://github.com/mainmatter/ember-test-selectors" rel="noopener noreferrer">Test selectors</a> (what should be tested and how are the selectors named?)</li> </ul> <p>Meanwhile, the consumer must provide these three:</p> <ul> <li>Data and translations (what should the component render?)</li> <li>Margin and padding for the container (so the component can play nice with others)</li> <li> <a href="https://guides.emberjs.com/release/in-depth-topics/patterns-for-actions" rel="noopener noreferrer">Callback functions</a> (when a user takes an action, what should the component do?)</li> </ul> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F19.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F19.png" alt=""></a></p> <p>How I separated styling—namely, the container doesn't set its margin and padding, but the consumer does with an extra <code>&lt;div&gt;</code>—may come as a surprise. I learned this from Sean Massa and Trek Glowacki a few years ago, and find that it really helps us reuse and refactor components. The rationale is, reusable components should only care about what happens inside. We encounter this idea also in <a href="https://github.com/ijlee2/ember-container-query" rel="noopener noreferrer">container queries</a>.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F20.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F20.png" alt=""></a></p> <p>Another thing to note here is data and translations. Before <a href="https://blog.emberjs.com/ember-3-25-released" rel="noopener noreferrer">Ember 3.25</a>, we would have had to use a bunch of arguments to pass these down. Now, thanks to <a href="https://guides.emberjs.com/release/components/block-content" rel="noopener noreferrer">named blocks</a>, the reusable component can focus on the layout, while the consumer on the content. Named blocks are one of my favorite features of Ember.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F21.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F21.png" alt=""></a></p> <p>A feature of Ember that I want you to use with caution is <a href="https://guides.emberjs.com/release/components/component-arguments-and-html-attributes" rel="noopener noreferrer">...attributes</a>, as they can easily destroy separation of concerns. I'll give you 2 examples.</p> <p>One time, I tried to replace flex with grid to simplify a reusable component, only to find out, many of the consumers had passed the <code>class</code> attribute and had overwritten the flex properties. Thanks to splattributes, implementation got leaked and the consumers are now forcing me to keep using flex.</p> <p>Another problem that I observed at CLARK is too many test selectors, because many consumers had passed their own. When the same DOM element is referred to in 7 different ways, refactoring the reusable component becomes tedious. Suddenly, I have to update multiple test files in different packages.</p> <p>In general, I think <code>...attributes</code> is a sign that the component wasn't designed right. Maybe it should ask the consumer to, instead, use arguments to define styles, named blocks to customize content, and test helpers to write tests. I want you to use the right tools to solve the right problems.</p> <h3> 2c. The right code depends on few </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F22.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F22.png" alt=""></a></p> <p>Just like arguments, every package that we install increases the chance that something goes wrong. But unlike arguments, we don't really have control over packages. If the package author doesn't do releases or they make breaking changes, our code can become stuck in time.</p> <p>Now, I'm not saying, write every code yourself and have zero dependencies. Instead, ask yourself: Is their code more <em>stable</em> than mine? To me, stable doesn't mean, there's a 1.0 release. It means, the package is well-written, -documented, -tested, and -supported. You can install the package only if the answer is yes.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F23.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F23.png" alt=""></a></p> <p>Of course, at times, you will need to install a package that is not stable. If so, try to <a href="https://en.wikipedia.org/wiki/Wrapper_function" rel="noopener noreferrer">wrap the code</a> that you need, then write tests to document the wrapper's input and output. This way, if the package turns out to be no go, you will have to replace the code in only 1 place: the wrapper.</p> <p>I'll tell you about a mistake that we had made at CLARK and how it's now affecting us with upgrading Ember. (It's a funny story and you're going to laugh, because you're not affected.)</p> <p>We use <a href="https://github.com/adopted-ember-addons/ember-file-upload" rel="noopener noreferrer">ember-file-upload</a> and I noticed, we are on <code>5.0.0-beta</code> when the latest is 8-something and I can't update Ember to 4 without updating <code>ember-file-upload</code> first.</p> <p>Well, it turns out, we came up with like 10 different ways to render <code>&lt;FileUpload&gt;</code> and, since the beta, the addon changed its API and styling drastically. So now, we have to fix deprecations, visual regressions, and failing tests for every one of these cases. If only we had come up with a wrapper component, tja.</p> <h2> 3. Solid foundation </h2> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F24.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F24.png" alt=""></a></p> <p>To help people design code right, we need a strong foundation—things like simple lint and test strategies, up-to-date dependencies, and short build and rebuild times. Replacing the foundation is a comparatively large task, but it's also something that we will have to do only once in a while.</p> <p>The question is, for an <em>existing</em> project, how do we replace the foundation without stopping everything else? The solution, again, is in increments.</p> <h3> 3a. Overhauling lint </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F25.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F25.png" alt=""></a></p> <p>A year ago, at CLARK, every package had different linter configurations, so we couldn't update packages like <code>eslint</code> and <code>typescript</code>. Furthermore, how we asked our developers to lint files was different from how we asked our CI.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F26.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F26.png" alt=""></a></p> <p>Fast forward to now, our project is set up like this: There are only 3 scripts for developers to remember because every package has them: <code>lint</code>, <code>lint:fix</code>, and <code>test</code>. CI runs the exact same scripts so we can easily reproduce issues locally.</p> <p>Second, we use the flag <code>--cache</code> and the package <a href="https://github.com/open-cli-tools/concurrently" rel="noopener noreferrer">concurrently</a> so that we can lint files faster and more exhaustively.</p> <p>Lastly, we have limited resource so we rely on the default as much as possible. Things like <a href="https://github.com/ember-cli/ember-cli/tree/master/blueprints" rel="noopener noreferrer">blueprints from ember-cli</a> and official plugins like <code>@tsconfig/ember</code>. We adopt 3rd-party plugins only if they are stable in the sense that I mentioned earlier.</p> <ul> <li><a href="https://github.com/tsconfig/bases/blob/main/bases/ember.json" rel="noopener noreferrer">@tsconfig/ember</a></li> <li><a href="https://github.com/eslint-community/eslint-plugin-n" rel="noopener noreferrer">eslint-plugin-n</a></li> <li><a href="https://github.com/lydell/eslint-plugin-simple-import-sort" rel="noopener noreferrer">eslint-plugin-simple-import-sort</a></li> <li><a href="https://github.com/infctr/eslint-plugin-typescript-sort-keys" rel="noopener noreferrer">eslint-plugin-typescript-sort-keys</a></li> <li><a href="https://github.com/hudochenkov/stylelint-order" rel="noopener noreferrer">stylelint-order</a></li> </ul> <p>And here is how we changed linting across 190 packages. It turns out, packages are not equal. Leaf-node packages (packages that don't depend on others) were actually seldom worked on, so we updated them all at once. Packages for a business domain belong together so they were updated together.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fapurx91zlnbsbka4851v.gif" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fapurx91zlnbsbka4851v.gif" alt="We can change linting in groups of packages"></a></p> <p>In a single day, we updated <code>eslint</code> to <code>v8</code> and reset all configurations by bypassing CI. We asked <code>lint:js</code> to return code 0, an unconditional success. Afterwards—again, in groups of packages—we reverted the scripts, ran auto-fix, and ignored errors that couldn't be fixed.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F31.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F31.png" alt=""></a></p> <p>With this divide-and-conquer strategy, it took me (one person) about 10 pull requests and no more than 5 days to introduce a change.</p> <h3> 3b. Spotting blockers </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F32.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F32.png" alt=""></a></p> <p>Next, we look out for deprecations and outdated packages that can block us from updating more critical dependencies like <code>ember-source</code>.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F33.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F33.png" alt=""></a></p> <p>To find deprecations, we can use <a href="https://github.com/mixonic/ember-cli-deprecation-workflow" rel="noopener noreferrer">ember-cli-deprecation-workflow</a> and create a to-do list. The addon does require that we have enough tests to avoid false negatives. Later, I'll show you how you can write simple tests when there aren't any. Another approach is to run the app and check <a href="https://github.com/emberjs/ember-inspector" rel="noopener noreferrer">Ember Inspector</a>'s Deprecations tab.</p> <p>Here are 3 deprecations that will likely affect many projects. You can visit <a href="https://deprecations.emberjs.com" rel="noopener noreferrer">deprecations.emberjs.com</a> to learn more.</p> <ul> <li> <code>implicit-injections</code> (v4)</li> <li> <code>this-property-fallback</code> (v4)</li> <li> <code>routing.transition-methods</code> (v5)</li> </ul> <p>I also gathered a list of important packages and the minimum version that you want to reach. It's important to update <code>ember-auto-import</code> and <code>ember-modifier</code> now, because more addons will move on to support <a href="https://github.com/embroider-build/embroider" rel="noopener noreferrer">Embroider</a>.</p> <ul> <li><a href="https://github.com/embroider-build/ember-auto-import" rel="noopener noreferrer">ember-auto-import@2</a></li> <li><a href="https://github.com/ember-modifier/ember-modifier" rel="noopener noreferrer">ember-modifier@3.2.7</a></li> <li><a href="https://github.com/ember-template-lint/ember-template-lint" rel="noopener noreferrer">ember-template-lint@5</a></li> <li><a href="https://github.com/eslint/eslint" rel="noopener noreferrer">eslint@8</a></li> <li><a href="https://github.com/microsoft/TypeScript" rel="noopener noreferrer">typescript@4.8.2</a></li> </ul> <h3> 3c. Short (re)build </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F36.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F36.png" alt=""></a></p> <p>To help people iterate on a solution many times, we need builds and rebuilds to be fast. A forewarning: High performance optimization isn't my expertise so I cannot give you definitive answers. Nonetheless, I'll share what we did at CLARK, which seemed to help lower the times. Maybe they can help you too.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F37.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F37.png" alt=""></a></p> <p>We ended up with 190 packages because of premature abstractions. By combining packages and removing dead code, we are now down to 150. In the process, we removed a few cyclic dependencies by creating a leaf-node package.</p> <p>Now, if there is a component used by many packages, see if you can simplify it. You can, for example, make it <a href="https://api.emberjs.com/ember/release/functions/@ember%2Fcomponent%2Ftemplate-only/templateOnly" rel="noopener noreferrer">template-only</a> and replace older syntax with newer ones.</p> <p>An ongoing project for us is to declare dependencies correctly so that we can adopt Embroider. Because we use <code>yarn</code> to manage the monorepo, many packages that had been created by copy-paste listed wrong dependencies. You can find unused dependencies by searching code for how they would have been used.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F38.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F38.png" alt=""></a></p> <p>Finally, if you have <a href="https://github.com/ember-cli/ember-cli/releases/tag/v3.15.0" rel="noopener noreferrer">ember-cli@3.15</a> or higher, there's a hidden feature that can make rebuilds faster. In <code>ember-cli-build.js</code>, simply set <code>BROCCOLI_ENABLED_MEMOIZE</code> to <code>true</code>. This happens by default in Embroider projects.</p> <h2> 4. Solving together </h2> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F39.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F39.png" alt=""></a></p> <p>My colleagues and I are in this lucky situation, where I can maintain code full-time, but that's still a bus factor of 1. It's important that I share knowledge and get more people involved. This year, we began to tackle tech debt together. Each quarter, we discuss ideas and decide what to work on.</p> <p>To show that every one of you has the power to make change, first, I will cover 5 techniques for refactoring. These are accessible and can be used on a daily basis. Next are codemods, something that's more advanced and takes time to do. Finally, we will think about how our interpersonal skills affect how we collaborate.</p> <h3> 4a. Refactors </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F40.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F40.png" alt=""></a></p> <p>There is this book on refactoring that I hate. It gives us 70 techniques and the examples are academic, so I could never tell which are actually important.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F41.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F41.png" alt=""></a></p> <p>I claim, we just need 5 to survive: Write tests, <a href="https://crunchingnumbers.live/2020/08/08/3-refactoring-techniques" rel="noopener noreferrer">rename things, make early exits, extract functions</a>, and remove dead code.</p> <h4> Write tests </h4> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F42.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F42.png" alt=""></a></p> <p>If your project doesn't have tests, you can use <a href="https://cli.emberjs.com/release/advanced-use/cli-commands-reference" rel="noopener noreferrer">Ember CLI</a> to write the simplest test, a tautology (<code>true</code> is equal to <code>true</code>). For example, you render a component and write <code>assert.ok(true)</code>, or you look up a service and assert that it is truthy.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F43.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F43.png" alt=""></a></p> <p>Even these placeholder tests provide two valuable information: the minimum data needed to initialize your object, and a guarantee that the object won't cause issues when you use it.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F44.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F44.png" alt=""></a></p> <p>You can learn more about <a href="https://crunchingnumbers.live/2019/10/11/write-tests-like-a-mathematician-part-3" rel="noopener noreferrer"><em>how</em> to write tests</a> from <a href="https://www.youtube.com/watch?v=uTjSHpJWQAY" rel="noopener noreferrer">my talk at EmberFest 2019</a>. The lessons from back then still apply today.</p> <h4> Rename things </h4> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F45.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F45.png" alt=""></a></p> <p>When you don't understand what a variable, condition, or function does, there's a chance that other people won't either. Once you understand the code better, give names that are descriptive.</p> <h4> Make early exits </h4> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F46.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F46.png" alt=""></a></p> <p>Nested conditions (in general, indentations to the right) are a recipe for disaster. They encourage us to keep nesting to handle new exceptions.</p> <p>You can fix this by making early exits. If there is code that happens when a condition is true, instead, you exit immediately when false, using <code>return</code>, <code>break</code>, or <code>continue</code>. Early exits help us simplify logic and move code to the left.</p> <h4> Extract functions </h4> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F47.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F47.png" alt=""></a></p> <p>At times, you will find a function that has many lines of code, but is actually performing a few key steps in sequence. If so, create a function for each key step and give a name that describes the step.</p> <p>This process of breaking a large function into smaller ones is called extraction. Once you extract functions, you have the option to move them to app/utils (“utilities”) and write unit tests.</p> <h4> Remove dead code </h4> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F48.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F48.png" alt=""></a></p> <p>Finally, if you see code that isn't used, delete it. By removing code, you can simplify assumptions, remove dependencies, and allow further refactors.</p> <p>To find dead code, you can use <code>git grep</code> or your code editor's Find tool. For searches to be accurate, though, your code has to be written well (a Catch-22) and, ideally, be statically analyzable. It's hard to match names that are dynamically generated.</p> <h3> 4b. Codemods </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F49.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F49.png" alt=""></a></p> <p>When you want to update many files to follow a new format, you might ask, should I write a codemod, a program to update the files for me? It depends.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F50.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F50.png" alt=""></a></p> <p>When you write a codemod, you pay the costs upfront. You have to first create and configure a package, write code, then write tests to test that code. This can take days or weeks. But once you have a codemod that is backed by tests, the returns are manifold. The codemod can update your project in a second and can be reused to help other projects migrate.</p> <p>Here's the crux: When your project has many variations in code because it hasn't been maintained, updating it by hand will be faster. A codemod will run into edge cases that may or may not occur in other projects, and every edge case that you handle is extra code that you have to maintain.</p> <p>Nonetheless, the ability to help others just might be the deciding factor for you. As a rule of thumb, consider writing a codemod if you can cover the usual 80%.</p> <p>To get started, I would've recommended two years ago Robert Jackson's <a href="https://github.com/rwjblue/codemod-cli" rel="noopener noreferrer">codemod-cli</a>, but this package is unmaintained, doesn't support TypeScript, and makes a divide-and-conquer strategy—taking small steps—hard to achieve.</p> <p>So I created <a href="https://github.com/ijlee2/codemod-utils" rel="noopener noreferrer">@codemod-utils</a>, a set of tools and conventions for writing codemods. I use it to power all of mine:</p> <ul> <li>blueprint-for-v2-addon (CLARK internal)</li> <li><a href="https://github.com/ijlee2/ember-codemod-args-to-signature/" rel="noopener noreferrer">ember-codemod-args-to-signature</a></li> <li><a href="https://github.com/ijlee2/ember-codemod-pod-to-octane" rel="noopener noreferrer">ember-codemod-pod-to-octane</a></li> <li><a href="https://github.com/ijlee2/embroider-css-modules/blob/main/packages/ember-codemod-remove-ember-css-modules" rel="noopener noreferrer">ember-codemod-remove-ember-css-modules</a></li> <li><a href="https://github.com/ijlee2/ember-codemod-v1-to-v2" rel="noopener noreferrer">ember-codemod-v1-to-v2</a></li> <li><a href="https://github.com/ijlee2/embroider-css-modules/tree/main/packages/type-css-modules" rel="noopener noreferrer">type-css-modules</a></li> </ul> <p>And just last week, I published a <a href="https://github.com/ijlee2/codemod-utils/tree/main/packages/cli" rel="noopener noreferrer">CLI</a>. You can use it to create a modern project that comes with lint, test, CI, and documentation out of the box.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F52.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F52.png" alt=""></a></p> <p>My hope is, we can lower the barrier enough that, if a person can write a function in Node.js, then they can start writing a codemod. I'd love to see more people writing one, given that <a href="https://emberjs.com/editions" rel="noopener noreferrer">Polaris</a> is coming up, and <a href="https://typed-ember.gitbook.io/glint" rel="noopener noreferrer">Glint</a> and <a href="https://github.com/ember-template-imports/ember-template-imports" rel="noopener noreferrer"><code>&lt;template&gt;</code>-tag</a> can use a higher adoption. Who knows? Maybe, some day, I will give a talk on codemods.</p> <h3> 4c. Different perspectives </h3> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F53.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F53.png" alt=""></a></p> <p>While solving problems together, I want you to think about your interpersonal skills and how they affect how you collaborate.</p> <p>Each of us, with a unique background, has a different way of thinking and verbalizing how we perceive the world. These differences surface when we discuss ideas and review each other's code. The more we are competent in our interpersonal skills, the better we can appreciate the differences and appreciate one another for who they are.</p> <p>We say interpersonal <em>skills</em> because they are something that we can learn by practice. I myself learned through Toastmasters, where I met many good people. Nowadays, with more information online, I recommend that you branch out and see what interests you.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F54.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F54.png" alt=""></a></p> <p>Back in Germany (and this time, it's real), you can stream shows called <a href="https://www.zdf.de/kultur/sags-mir" rel="noopener noreferrer">Sag's mir</a>, <a href="https://www.zdf.de/kultur/unter-anderen" rel="noopener noreferrer">Unter Anderen</a>, and <a href="https://www.zdf.de/kultur/13-fragen" rel="noopener noreferrer">13 Fragen</a>, where 2-6 people with opposing ideas carry a conversation that is personal and civilized. The goal isn't to win the argument, but to listen to each other and come up with a compromise. I really like these shows because they can teach us what makes a discussion go well.</p> <h2> 5. Future is now </h2> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F55.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F55.png" alt=""></a></p> <p>Last but not least, I want to show you that you can move towards the future even when your project is behind. For example, you can install polyfills to start modernizing syntax, and update <code>ember-cli</code> to the latest, independently of <code>ember-source</code>:</p> <ul> <li><a href="https://github.com/ember-polyfills/ember-angle-bracket-invocation-polyfill" rel="noopener noreferrer">ember-angle-bracket-invocation-polyfill</a></li> <li><a href="https://www.npmjs.com/package/ember-cached-decorator-polyfill" rel="noopener noreferrer">ember-cached-decorator-polyfill</a></li> <li><a href="https://github.com/ember-polyfills/ember-functions-as-helper-polyfill" rel="noopener noreferrer">ember-functions-as-helper-polyfill</a></li> <li><a href="https://github.com/ember-polyfills/ember-in-element-polyfill" rel="noopener noreferrer">ember-in-element-polyfill</a></li> <li><a href="https://github.com/ember-polyfills/ember-named-blocks-polyfill" rel="noopener noreferrer">ember-named-blocks-polyfill</a></li> <li><a href="https://github.com/ember-polyfills/ember-on-modifier" rel="noopener noreferrer">ember-on-modifier</a></li> <li><a href="https://github.com/ctjhoa/ember-unique-id-helper-polyfill" rel="noopener noreferrer">ember-unique-id-helper-polyfill</a></li> </ul> <p>If you maintain a v1 addon, you can enable two <a href="https://github.com/ember-cli/ember-try" rel="noopener noreferrer">ember-try</a> scenarios (<code>embroider-safe</code> and <code>embroider-optimized</code>) so that you can discover issues early and create a plan to adopt the v2 format. You can also support <a href="https://github.com/ijlee2/ember-container-query/releases/tag/3.1.0" rel="noopener noreferrer">Glint</a> and <a href="https://github.com/ijlee2/ember-container-query/releases/tag/3.2.0" rel="noopener noreferrer"><code>&lt;template&gt;</code>-tag</a> users, even before you <a href="https://github.com/ijlee2/ember-codemod-v1-to-v2" rel="noopener noreferrer">migrate to v2</a>.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F57.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F57.png" alt=""></a></p> <p>This April, at CLARK, we started using a private package registry. It helped us extract linter configurations from the monorepo, so that we can reuse them in other projects and standardize how we write code. The registry also helped us set up another monorepo (with <code>pnpm</code>), where we extracted addons, converted them to v2, introduced <a href="https://github.com/ijlee2/embroider-css-modules/tree/main/packages/embroider-css-modules" rel="noopener noreferrer">embroider-css-modules</a>, supported Glint and <code>&lt;template&gt;</code>-tag, and wrote test apps to make sure that we are ready for the future.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F58.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F58.png" alt=""></a></p> <p>By thinking a bit outside of the box, you just might be able to solve many problems at once.</p> <h2> 6. Closing </h2> <p>In conclusion, when your project is currently hard to maintain and extend, you may feel overwhelmed and hopeless, but please—don't give up. By taking small steps and iterating on a solution, you can introduce change that will help you and others. And you don't have to do it alone. Ask your team and the community that we have for help.</p> <p>In 1 year, when we are back at <a href="https://www.emberconf.com/" rel="noopener noreferrer">EmberConf</a>, I'd love to hear how your project is doing. Maybe you'll strike a conversation with me, in the hallway or on <a href="https://discord.gg/emberjs" rel="noopener noreferrer">Discord</a>, or present a talk like I did today. Until then, mach's gut. Take care.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F59.png" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2023%2F07%2F59.png" alt=""></a></p> ember javascript webdev beginners Isaac Lee Mon, 31 Aug 2020 17:09:53 +0000 https://dev.to/ijlee2/powering-the-together-framework-1ieo https://dev.to/ijlee2/powering-the-together-framework-1ieo <p>In 2020, <a href="https://emberjs.com/">Ember.js</a> earned an unofficial nickname—The <em>Together</em> Framework. Since inception, Ember championed 3 things that led to this moniker:</p> <ul> <li>Share solutions (via battery-included framework and complementary <a href="https://emberobserver.com/">addons</a>)</li> <li>Adopt new technologies via <a href="https://github.com/emberjs/rfcs">RFCs</a> (open to all)</li> <li>Pave migration paths (e.g. <a href="https://emberjs.com/deprecations/">deprecation warnings</a>, <a href="https://github.com/ember-codemods">codemods</a>) so that developers who maintain older apps aren't abandoned</li> </ul> <p>Because developers and teams follow a set of conventions, it's particularly easy to write GitHub Actions workflows that can be <strong>shared among Ember apps and addons</strong>.</p> <h3> My Workflow </h3> <p>For the hackathon, I created workflow templates for Ember apps and addons.</p> <p>✅ The workflow for Ember apps has several features:</p> <ul> <li>Leverages 5 <a href="https://github.com/actions/">officially supported actions</a> (all <code>v2</code> or <code>v2-beta</code>)</li> <li>Lints files and dependencies</li> <li>Runs tests in parallel</li> <li>Takes <a href="http://percy.io/">Percy</a> snapshots in parallel</li> <li>Caches <code>node_modules</code> for faster run</li> <li>Pre-builds test app for faster run</li> <li>Deploys the app (to any provider that <a href="http://ember-cli-deploy.com/">ember-cli-deploy</a> supports, such as <a href="https://github.com/ef4/ember-cli-deploy-git">GitHub Pages</a>, <a href="https://github.com/exelord/ember-cli-deploy-netlify-cli">Netlify</a>, and <a href="https://github.com/ember-cli-deploy/ember-cli-deploy-s3">S3</a>)</li> </ul> <p>✅ The workflow for Ember addons has several features:</p> <ul> <li>Leverages 5 <a href="https://github.com/actions/">officially supported actions</a> (all <code>v2</code> or <code>v2-beta</code>)</li> <li>Lints files and dependencies</li> <li>Runs tests in parallel</li> <li>Takes <a href="http://percy.io/">Percy</a> snapshots in parallel</li> <li>Caches <code>node_modules</code> for faster run</li> <li>Pre-builds test app for faster run</li> <li>Ensures that addon works with <a href="https://github.com/ember-cli/ember-try">LTS, release, beta, and canary versions</a> of Ember</li> </ul> <p>To top these off, I created <a href="https://github.com/ijlee2/inspect-workflow-runs">inspect-workflow-runs</a>. You can analyze past workflow runs and make a data-driven decision for calibrating <code>timeout-minutes</code>. (The default value is <a href="https://docs.github.com/actions/reference/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes">360 minutes</a>, which can lead to accidentally running out of minutes in private repos.)</p> <h3> Submission Category: </h3> <ul> <li>Maintainer Must-Haves</li> </ul> <h3> Yaml File or Link to Code </h3> <p>I created 4 workflow templates for the hackathon. They account for Ember addon vs. app, and yarn vs. npm.</p> <ul> <li>Ember addons: <a href="https://gist.github.com/ijlee2/25004d700cd008ee08ecc4873c109a5b">yarn</a>, <a href="https://gist.github.com/ijlee2/fba20304670b8d2b71f0b81cd07ea026">npm</a> </li> <li>Ember apps: <a href="https://gist.github.com/ijlee2/1c864ebe96a55f239e80800829ef0bf4">yarn</a>, <a href="https://gist.github.com/ijlee2/6576ae82895d522ccc0695518c2a6ce7">npm</a> </li> </ul> <p>My main entry for the hackathon is <a href="https://gist.github.com/ijlee2/25004d700cd008ee08ecc4873c109a5b">Ember addons - yarn</a>. Addons like <code>ember-container-query</code> are the open-sourced npm packages that bring the Ember community together to develop, share, and support. 🧡</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--Az_zNVNB--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/08/cover_image_github_actions.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--Az_zNVNB--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/08/cover_image_github_actions.png" alt="A workflow run for Ember Container Query shows 20 jobs that completed in 3 minutes." width="800" height="427"></a></p> A workflow run for <code>ember-container-query</code> shows 20 jobs that completed in 3 minutes. Thanks to CI and thorough testing, the addon has had 0 bug reports. <h3> Additional Resources / Info </h3> <p>To learn more about writing GitHub Actions workflows for Ember projects, I recommend my blog posts:</p> <ul> <li><a href="https://crunchingnumbers.live/2020/03/17/ci-with-github-actions-for-ember-apps/">CI with GitHub Actions for Ember Apps: Part 1</a></li> <li><a href="https://crunchingnumbers.live/2020/08/31/ci-with-github-actions-for-ember-apps-part-2/">CI with GitHub Actions for Ember Apps: Part 2</a></li> </ul> <p>The workflow templates that I built now power a few open source projects for the Ember community:</p> <ul> <li><a href="https://github.com/ijlee2/ember-container-query/blob/main/.github/workflows/ci.yml">ember-container-query</a></li> <li><a href="https://github.com/ember-learn/ember-octane-vs-classic-cheat-sheet/blob/master/.github/workflows/ci-cd.yml">ember-octane-vs-classic-cheat-sheet</a></li> <li><a href="https://github.com/dknutsen/ember-themed/blob/master/.github/workflows/ci.yml">ember-themed</a></li> <li><a href="https://github.com/ember-learn/ember-times-tools/blob/main/.github/workflows/ci.yml">ember-times-tools</a></li> <li><a href="https://github.com/ember-learn/whats-new-in-emberland/blob/master/.github/workflows/ci.yml">whats-new-in-emberland</a></li> </ul> <p>While I created the workflow templates on my own, my knowledge and experience with GitHub Actions stand upon those of amazing developers in the Ember community. I'd like to recognize:</p> <ul> <li><a href="https://github.com/dknutsen">Dan Knutsen</a></li> <li><a href="https://github.com/kategengler">Katie Gengler</a></li> <li><a href="https://github.com/jenweber">Jen Weber</a></li> <li><a href="https://github.com/buschtoens">Jan Buschtöns</a></li> <li><a href="https://github.com/dfreeman">Dan Freeman</a></li> <li><a href="http://github.com/NullVoxPopuli">Preston Sego</a></li> </ul> actionshackathon ember javascript cicd Isaac Lee Mon, 31 Aug 2020 16:05:49 +0000 https://dev.to/ijlee2/ci-with-github-actions-for-ember-apps-part-2-30ph https://dev.to/ijlee2/ci-with-github-actions-for-ember-apps-part-2-30ph <p>2020 has been a tough, frail year. Last week, I joined many people who were laid off. Still I'm grateful for the good things that came out like <a href="https://www.youtube.com/watch?v=BE7vBk_zLA4&amp;list=PL8tkzXKlhGxn8vedFOKUngfcdnz6MV40M">Dreamland</a> and <a href="https://crunchingnumbers.live/2020/03/17/ci-with-github-actions-for-ember-apps/">CI with GitHub Actions for Ember Apps</a>.</p> <p>With GitHub Actions, I cut down CI runtimes for work projects to 3-4 minutes (with lower variance and more tests since March). I also noticed more and more Ember projects switching to GitHub Actions so I felt like a pioneer.</p> <p>Today, I want to patch my original post and cover 3 new topics:</p> <ul> <li>How to migrate to v2 actions</li> <li>How to lower runtime cost</li> <li>How to continuously deploy (with <a href="http://ember-cli-deploy.com/">ember-cli-deploy</a>)</li> </ul> <p>I will assume that you read <a href="https://crunchingnumbers.live/2020/03/17/ci-with-github-actions-for-ember-apps/">Part 1</a> and are familiar with my workflow therein. Towards the end, you can find new workflow templates for Ember addons and apps.</p> <h2> 1. How to Migrate to v2 Actions </h2> <p>In Part 1, you met 3 actions that are officially supported by GitHub:</p> <ul> <li><a href="https://github.com/actions/checkout">actions/checkout</a></li> <li><a href="https://github.com/actions/setup-node">actions/setup-node</a></li> <li><a href="https://github.com/actions/cache">actions/cache</a></li> </ul> <p>You can check out the README to find new features and improvements in v2. If you followed my workflow, you should be able to use v2 without a problem.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="na">jobs</span><span class="pi">:</span> <span class="na">lint</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Lint files and dependencies</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/checkout@v2</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Use Node.js ${{ env.NODE_VERSION }}</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/setup-node@v2-beta</span> <span class="na">with</span><span class="pi">:</span> <span class="na">node-version</span><span class="pi">:</span> <span class="s">${{ env.NODE_VERSION }}</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Get Yarn cache path</span> <span class="na">id</span><span class="pi">:</span> <span class="s">yarn-cache-dir-path</span> <span class="na">run</span><span class="pi">:</span> <span class="s">echo "::set-output name=dir::$(yarn cache dir)"</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Cache Yarn cache and node_modules</span> <span class="na">id</span><span class="pi">:</span> <span class="s">cache-dependencies</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/cache@v2</span> <span class="na">with</span><span class="pi">:</span> <span class="na">path</span><span class="pi">:</span> <span class="pi">|</span> <span class="s">${{ steps.yarn-cache-dir-path.outputs.dir }}</span> <span class="s">node_modules</span> <span class="na">key</span><span class="pi">:</span> <span class="s">${{ runner.os }}-${{ env.NODE_VERSION }}-${{ hashFiles('**/yarn.lock') }}</span> <span class="na">restore-keys</span><span class="pi">:</span> <span class="s">${{ runner.os }}-${{ env.NODE_VERSION }}-</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Install dependencies</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn install --frozen-lockfile</span> <span class="na">if</span><span class="pi">:</span> <span class="s">steps.cache-dependencies.outputs.cache-hit != 'true'</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Lint</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn lint</span> </code></pre> </div> <p>Notice that <code>actions/cache@v2</code> allows <strong>caching multiple things in one step</strong>. As a result, the cache retrieval step (line 29) is simpler.</p> <h2> 2. How to Lower Runtime Cost </h2> <p>I neglected to warn cost last time. For private repos, where production apps are likely stored, GitHub Actions charges you by the minute. 2020 taught me that money doesn't grow on trees.</p> <p>You can control 3 things to lower cost:</p> <ul> <li>Set operating system</li> <li>Lower job runtime</li> <li>Lower <code>timeout-minutes</code> </li> </ul> <p>Even if your repo is public and immune from charge, I recommend the last 2 practices to lower the overall runtime.</p> <h3> a. Set Operating System </h3> <p>In Part 1, I suggested that you can use <code>matrix</code> to test the app against vari ous operating systems. I must redact because jobs that run on Windows and Mac <a href="https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-actions#about-billing-for-github-actions">cost 2 and 10 times as much</a> as those on Linux. The rate difference also applies to storage used by GitHub Actions artifacts, which we will soon leverage.</p> <p>Unless you have a compelling business requirement, <strong>run jobs on Linux only</strong>:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="na">jobs</span><span class="pi">:</span> <span class="na">lint</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Lint files and dependencies</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">ubuntu-latest</span> </code></pre> </div> <h3> b. Lower Job Runtime </h3> <p>When a workflow runs, you pay for the <em>sum</em> of all job runtimes. You don't pay for the workflow runtime (except in the sense of feedback loop).</p> <p>Our workflow has 1 lint and 4 test jobs. Suppose these jobs took 1:40, 3:20, 4:00, 4:30, and 3:40 minutes to run. In total, the jobs took,<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>1:40 + 3:20 + 4:00 + 4:30 + 3:40 = 17.10 minutes </code></pre> </div> <p>We round up that number, then multiply by the per-minute rate ($0.008/min for Linux) to arrive at the cost:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>18 minutes × $0.008/minute = $0.144 </code></pre> </div> <p>14.4 cents seem trivial until you realize that your team can make hundreds or thousands of commits each month. (See <a href="https://crunchingnumbers.live/2020/03/17/ci-with-github-actions-for-ember-apps/">Part 1, Section 1c</a> to learn more about configuring <code>on</code> correctly.)</p> <p>There's a silver lining for Ember developers. The predominant jobs in our workflow are tests. A test job takes a while to run because it needs to build the app. What if you can <strong>build the test app once</strong> and pass it to each job—a form of caching?</p> <p>Since <a href="https://github.com/ember-cli/ember-cli/pull/4874">2015</a>, <code>ember test</code> has let you pass <code>--path</code> to tell there's a pre-built <code>dist</code> folder somewhere. You can set the location thanks to 2 officially-supported actions:</p> <ul> <li><a href="https://github.com/actions/upload-artifact">actions/upload-artifact</a></li> <li><a href="https://github.com/actions/download-artifact">actions/download-artifact</a></li> </ul> <p>Even better, the <code>--path</code> flag works with <a href="https://ember-cli.com/ember-exam/docs/randomization-iterator">ember-exam</a> and <a href="https://docs.percy.io/docs/ember">@percy/ember</a>. Here is a simplified update:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="na">jobs</span><span class="pi">:</span> <span class="na">build-app</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Build app for testing</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">ubuntu-latest</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Build app</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn build:test</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Upload app</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/upload-artifact@v2</span> <span class="na">with</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">dist</span> <span class="na">path</span><span class="pi">:</span> <span class="s">dist</span> <span class="na">test-app</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test app</span> <span class="na">needs</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">build-app</span><span class="pi">]</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">ubuntu-latest</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">partition</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">1</span><span class="pi">,</span> <span class="nv">2</span><span class="pi">,</span> <span class="nv">3</span><span class="pi">,</span> <span class="nv">4</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Download app</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/download-artifact@v2</span> <span class="na">with</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">dist</span> <span class="na">path</span><span class="pi">:</span> <span class="s">dist</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">percy/exec-action@v0.3.0</span> <span class="na">with</span><span class="pi">:</span> <span class="na">custom-command</span><span class="pi">:</span> <span class="s">yarn test --partition=${{ matrix.partition }} --path=dist</span> <span class="na">env</span><span class="pi">:</span> <span class="na">PERCY_PARALLEL_NONCE</span><span class="pi">:</span> <span class="s">${{ env.PERCY_PARALLEL_NONCE }}</span> <span class="na">PERCY_PARALLEL_TOTAL</span><span class="pi">:</span> <span class="s">${{ env.PERCY_PARALLEL_TOTAL }}</span> <span class="na">PERCY_TOKEN</span><span class="pi">:</span> <span class="s">${{ secrets.PERCY_TOKEN }}</span> </code></pre> </div> <p>Notice the use of <code>needs</code> (line 17) to indicate a dependency among jobs. All <code>test-app</code> jobs won't start until the <code>build-app</code> job has finished.</p> <p>Although the workflow performs 1 additional job, the total runtime can be less because tests can finish sooner. When I introduced this change at work, I saw a 33% decrease (6-8 minutes) in billable minutes. That's 50% more runs for the same cost.</p> <p>The last thing to note is, we must build the Ember app in the test environment (line 7). The default <code>build</code> script makes a production build so I wrote <code>build:test</code> to make a test build. If you pass a production build, the tests won't run and will eventually time out (in CI and locally):<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code>message: <span class="o">&gt;</span> Error: Browser failed to connect within 120s. testem.js not loaded? Stderr: <span class="o">[</span>0824/133551.179006:ERROR:xattr.cc<span class="o">(</span>63<span class="o">)]</span> setxattr org.chromium.crashpad.database.initialized on file /var/folders/2z/93zyyhx13rs879qr8rzyxrb40000gn/T/: Operation not permitted <span class="o">(</span>1<span class="o">)</span> <span class="o">[</span>0824/133551.180908:ERROR:file_io.cc<span class="o">(</span>89<span class="o">)]</span> ReadExactly: expected 8, observed 0 <span class="o">[</span>0824/133551.182193:ERROR:xattr.cc<span class="o">(</span>63<span class="o">)]</span> setxattr org.chromium.crashpad.database.initialized on file /var/folders/2z/93zyyhx13rs879qr8rzyxrb40000gn/T/: Operation not permitted <span class="o">(</span>1<span class="o">)</span> DevTools listening on ws://127.0.0.1:63192/devtools/browser/9ffa155c-99b3-4f7f-a53e-b23cff1bf743 <span class="o">[</span>0824/133551.670401:ERROR:command_buffer_proxy_impl.cc<span class="o">(</span>122<span class="o">)]</span> ContextResult::kTransientFailure: Failed to send GpuChannelMsg_CreateCommandBuffer. </code></pre> </div> <h3> c. Lower timeout-minutes </h3> <p>GitHub Actions doesn't emphasize the need to set <code>timeout-minutes</code>. It's how long a job can run (stall) before GitHub Actions cancels the workflow. You're still charged for the run so it's important to know that the <a href="https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes">default timeout is 360 minutes</a> (!!).</p> <p>In short, if a workflow is to fail, let it <strong>fail fast</strong>. Make sure to set a low <code>timeout-minutes</code> for each job:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="na">jobs</span><span class="pi">:</span> <span class="na">build-app</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Build app for testing</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">ubuntu-latest</span> <span class="na">timeout-minutes</span><span class="pi">:</span> <span class="m">7</span> <span class="na">lint</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Lint files and dependencies</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">ubuntu-latest</span> <span class="na">timeout-minutes</span><span class="pi">:</span> <span class="m">7</span> <span class="na">test-app</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test app</span> <span class="na">needs</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">build-app</span><span class="pi">]</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">ubuntu-latest</span> <span class="na">timeout-minutes</span><span class="pi">:</span> <span class="m">7</span> </code></pre> </div> <p>A good initial value is how long build, lint, and test take locally, plus some wiggle room. Over time, however, you will want to observe runtimes and calibrate timeout.</p> <p>To help you make a data-driven decision, I created <a href="https://github.com/ijlee2/inspect-workflow-runs">inspect-workflow-runs</a>. The script finds past runs and recommends timeout based on 95% confidence interval:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>timeout-minutes ≈ x̅ + 2s </code></pre> </div> <p>Speaking of failing fast, GitHub Actions lets you <a href="https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast">cancel in-progress jobs</a> if any <code>matrix</code> job fails. This may be useful if you use <a href="https://github.com/ember-cli/ember-try">ember-try</a> or <a href="https://crunchingnumbers.live/2020/06/07/container-queries-cross-resolution-testing/">cross-resolution testing</a>.</p> <h2> 3. How to Continuously Deploy </h2> <p>In Part 1, I mentioned auto-deployment with <a href="https://www.heroku.com/">Heroku</a>. Since then, I got to deploy Ember apps to <a href="https://pages.github.com/">GitHub Pages</a> and <a href="https://www.netlify.com/">Netlify</a> thanks to open source work. I became curious about deploying apps from a GitHub Actions workflow.</p> <p>The Ember community has a dedicated addon called <a href="http://ember-cli-deploy.com/">ember-cli-deploy</a>. It has several plugins so that you can customize the deployment pipeline. Afterwards, you call <code>ember deploy production</code>, which you can certainly do from a workflow. The hard parts may be building the pipeline and passing your credentials.</p> <p>As a concrete example, we'll look at <strong>deploying to GitHub Pages</strong> with the plugin <a href="https://github.com/ef4/ember-cli-deploy-git">ember-cli-deploy-git</a>. I'll cover a basic setup and 2 ways to pass credentials. You can review the <a href="https://github.com/ember-learn/ember-octane-vs-classic-cheat-sheet/pull/58">changes to ember-octane-vs-classic-cheat-sheet</a> to see an implementation.</p> <p>As for deploying to Netlify, although there is a <a href="https://github.com/exelord/ember-cli-deploy-netlify-cli">plugin</a>, I'd use the standalone <a href="https://github.com/shipshapecode/ember-cli-netlify">ember-cli-netlify</a> for simple static sites. Netlify can listen to a push to the default branch (similarly to Heroku) so we just need something to handle routing. You can review the <a href="https://github.com/ijlee2/ember-container-query/pull/54/files">changes to ember-container-query</a>.</p> <h3> a. Setup </h3> <h4> Step 1 </h4> <p>We'll deploy the app to the <code>gh-pages</code> branch. After we create the branch,<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code>git checkout <span class="nt">--orphan</span> gh-pages git commit <span class="nt">--allow-empty</span> <span class="nt">-m</span> <span class="s1">'Created gh-pages branch for deployment'</span> git push <span class="nt">-u</span> origin gh-pages </code></pre> </div> <p>we ask GitHub Pages to build the site from <code>gh-pages</code>.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--SMTAlCZq--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/08/section_3a_github_pages.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--SMTAlCZq--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/08/section_3a_github_pages.png" alt="Select the deploy branch in Settings - Options - GitHub Pages." width="800" height="400"></a></p> Select the deploy branch in Options - GitHub Pages. <h4> Step 2 </h4> <p>Let's come back to the default branch. We need to install a few addons:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code>ember <span class="nb">install </span>ember-cli-deploy ember-cli-deploy-build ember-cli-deploy-git </code></pre> </div> <p>The command will create <code>config/deploy.js</code>. For now, we can leave this file alone. We'll look at it later in the context of setting credentials.</p> <p>Do update <code>config/environment.js</code> so that GitHub Pages understands the routing of the app:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// config/environment.js</span> <span class="dl">'</span><span class="s1">use strict</span><span class="dl">'</span><span class="p">;</span> <span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">environment</span><span class="p">)</span> <span class="p">{</span> <span class="kd">let</span> <span class="nx">ENV</span> <span class="o">=</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span> <span class="k">if</span> <span class="p">(</span><span class="nx">environment</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">production</span><span class="dl">'</span><span class="p">)</span> <span class="p">{</span> <span class="nx">ENV</span><span class="p">.</span><span class="nx">rootURL</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">/your-repo-name</span><span class="dl">'</span><span class="p">;</span> <span class="nx">ENV</span><span class="p">.</span><span class="nx">locationType</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">hash</span><span class="dl">'</span><span class="p">;</span> <span class="p">}</span> <span class="k">return</span> <span class="nx">ENV</span><span class="p">;</span> <span class="p">};</span> </code></pre> </div> <h4> Step 3 </h4> <p>Finally, create a <code>deploy</code> script in <code>package.json</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight json"><code><span class="p">{</span><span class="w"> </span><span class="nl">"scripts"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"deploy"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ember deploy production"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre> </div> <p>Now, we can run <code>yarn deploy</code> to deploy the app from the local machine. Let's look at how to deploy from the workflow next.</p> <h3> b. Create a Deploy Key </h3> <p>We can't simply add a step that runs <code>yarn deploy</code> because GitHub Actions will ask for authentication. When everything is meant to be automated, how do you authenticate?</p> <p>One solution is to check the public key against a private. We can store the latter as a secret environment variable for the workflow, much like we had with the Percy token. The authentication details are hidden thanks to the <a href="https://github.com/dfreeman/ember-cli-deploy-git-ci">ember-cli-deploy-git-ci</a> plugin.</p> <h4> Step 1 </h4> <p>Install the plugin and generate a key pair.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code>ember <span class="nb">install </span>ember-cli-deploy-git-ci ssh-keygen <span class="nt">-t</span> rsa <span class="nt">-b</span> 4096 <span class="nt">-N</span> <span class="s1">''</span> <span class="nt">-f</span> deploy_key </code></pre> </div> <p>The public key (<code>deploy_key.pub</code>) belongs to <strong>Deploy keys</strong> in the repo's Settings page. The private key (<code>deploy_key</code>) goes to <strong>Secrets</strong> and becomes an environment variable called <code>DEPLOY_KEY</code>.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--AkfnnJNl--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/08/section_3b_public_key.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--AkfnnJNl--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/08/section_3b_public_key.png" alt="The public key goes to Settings - Deploy keys." width="800" height="400"></a></p> The public key goes to Deploy keys. <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--UgYSYhAv--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/08/section_3b_private_key.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--UgYSYhAv--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/08/section_3b_private_key.png" alt="The private key goes to Settings - Secrets." width="800" height="400"></a></p> The private key goes to Secrets. <p>After saving these keys in GitHub, please delete <code>deploy_key.pub</code> and <code>deploy_key</code> so that they won't be committed to the repo.</p> <h4> Step 2 </h4> <p>We update <code>config/deploy.js</code> to indicate the presence of an SSH key:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// config/deploy.js</span> <span class="dl">'</span><span class="s1">use strict</span><span class="dl">'</span><span class="p">;</span> <span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">deployTarget</span><span class="p">)</span> <span class="p">{</span> <span class="kd">let</span> <span class="nx">ENV</span> <span class="o">=</span> <span class="p">{</span> <span class="na">build</span><span class="p">:</span> <span class="p">{},</span> <span class="na">git</span><span class="p">:</span> <span class="p">{</span> <span class="na">repo</span><span class="p">:</span> <span class="dl">'</span><span class="s1">git@github.com:your-username/your-repo-name.git</span><span class="dl">'</span><span class="p">,</span> <span class="p">},</span> <span class="dl">'</span><span class="s1">git-ci</span><span class="dl">'</span><span class="p">:</span> <span class="p">{</span> <span class="na">enabled</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="na">deployKey</span><span class="p">:</span> <span class="nx">process</span><span class="p">.</span><span class="nx">env</span><span class="p">.</span><span class="nx">SECRET_KEY</span><span class="p">,</span> <span class="p">},</span> <span class="p">};</span> <span class="p">...</span> <span class="k">return</span> <span class="nx">ENV</span><span class="p">;</span> <span class="p">};</span> </code></pre> </div> <h4> Step 3 </h4> <p>Finally, we add a deploy job to the workflow. We can use <code>needs</code> and <code>if</code> to describe when the app should be deployed (e.g. when there is a push to the <code>main</code> branch).</p> <p>Here's a simplified update:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="na">jobs</span><span class="pi">:</span> <span class="na">deploy-app</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Deploy app</span> <span class="na">needs</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">lint</span><span class="pi">,</span> <span class="nv">test-app</span><span class="pi">]</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">ubuntu-latest</span> <span class="na">timeout-minutes</span><span class="pi">:</span> <span class="m">7</span> <span class="na">if</span><span class="pi">:</span> <span class="s">github.event_name == 'push' &amp;amp;&amp;amp; github.ref == 'refs/heads/main'</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/checkout@v2</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Deploy</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn deploy</span> <span class="na">env</span><span class="pi">:</span> <span class="na">DEPLOY_KEY</span><span class="pi">:</span> <span class="s">${{ secrets.DEPLOY_KEY }}&lt;/pre&gt;</span> </code></pre> </div> <h3> c. Reuse Auth Token </h3> <p>Thanks to <code>actions/checkout@v2</code>, there's an easier way to authenticate—one that doesn't require <code>ember-cli-deploy-git-ci</code>.</p> <p>While a job runs, the checkout action persists the auth token in the local git config. As a result, we can set GitHub Actions as the user who wants to deploy the app, but pass our auth token instead:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="na">jobs</span><span class="pi">:</span> <span class="na">deploy-app</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Deploy app</span> <span class="na">needs</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">lint</span><span class="pi">,</span> <span class="nv">test-app</span><span class="pi">]</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">ubuntu-latest</span> <span class="na">timeout-minutes</span><span class="pi">:</span> <span class="m">5</span> <span class="na">if</span><span class="pi">:</span> <span class="s">github.event_name == 'push' &amp;amp;&amp;amp; github.ref == 'refs/heads/main'</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/checkout@v2</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Set up Git user</span> <span class="na">run</span><span class="pi">:</span> <span class="pi">|</span> <span class="s"># Set up a Git user for committing</span> <span class="s">git config --global user.name "GitHub Actions"</span> <span class="s">git config --global user.email "actions@users.noreply.github.com"</span> <span class="s"># Copy the Git Auth from the local config</span> <span class="s">git config --global "http.https://github.com/.extraheader" \</span> <span class="s">"$(git config --local --get http.https://github.com/.extraheader)"</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Deploy</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn deploy</span> </code></pre> </div> <p>Last but not least, we provide an HTTPS URL in <code>config/deploy.js</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// config/deploy.js</span> <span class="dl">'</span><span class="s1">use strict</span><span class="dl">'</span><span class="p">;</span> <span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">deployTarget</span><span class="p">)</span> <span class="p">{</span> <span class="kd">let</span> <span class="nx">ENV</span> <span class="o">=</span> <span class="p">{</span> <span class="na">build</span><span class="p">:</span> <span class="p">{},</span> <span class="na">git</span><span class="p">:</span> <span class="p">{</span> <span class="na">repo</span><span class="p">:</span> <span class="dl">'</span><span class="s1">https://github.com/your-username/your-repo-name.git</span><span class="dl">'</span><span class="p">,</span> <span class="p">},</span> <span class="p">};</span> <span class="p">...</span> <span class="k">return</span> <span class="nx">ENV</span><span class="p">;</span> <span class="p">};</span> </code></pre> </div> <h2> 4. Conclusion </h2> <p>Thanks to shared solutions in Ember (the <em>Together</em> Framework) and new features in v2 actions, we saw that CI/CD with GitHub Actions continues to work well for Ember apps and addons.</p> <p>We should watch out for long-running jobs because they cost money (even for public repos in the forms of feedback loop and developer's time). In Part 1, we learned to save time by running tests in parallel and caching <code>node_modules</code>. In Part 2, by building the test app once and employing a fail-fast strategy.</p> <p>If you haven't yet, I hope that you will give GitHub Actions a try and share what you learned. I look forward to discover more ways to optimize and enhance workflows.</p> <h2> 5. Notes </h2> <p>A few sections in Part 2 were possible thanks to the Ember community:</p> <ul> <li> <a href="https://github.com/dknutsen">Dan Knutsen</a> showed me how to pre-build the app for tests.</li> <li> <a href="https://github.com/kategengler">Katie Gengler</a> created the pre-build example in <a href="https://github.com/emberjs/ember.js/blob/master/.github/workflows/ci.yml#L36-L63">ember.js</a> and directed Dan to it.</li> <li> <a href="https://github.com/jenweber">Jen Weber</a> walked me through how to use <code>ember-cli-deploy-git</code>.</li> <li> <a href="https://github.com/buschtoens">Jan Buschtöns</a> and <a href="https://github.com/dfreeman">Dan Freeman</a> found a way to continuously deploy to GitHub Pages without <code>ember-cli-deploy-git-ci</code>. They shared their solution on <a href="https://discordapp.com/channels/480462759797063690/485881813370273792/745992323485401150">Discord</a>.</li> </ul> <p>Katie kindly informed me that it's also possible to pre-build an addon's demo app for every <code>ember-try</code> scenario. (I wanted to test an addon at different window sizes.)<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code>ember try:one scenario-name <span class="nt">---</span> ember build <span class="nt">--environment</span><span class="o">=</span><span class="nb">test</span> </code></pre> </div> <p>Katie recommends caching <code>dist</code> (with a unique hash based on Node version, scenario name, and lockfile) over uploading it as an artifact. This is to avoid the possibility of passing the wrong <code>dist</code> to a scenario.</p> <p>I posted new workflow templates on GitHub Gist.</p> <ul> <li>Ember addons: <a href="https://gist.github.com/ijlee2/25004d700cd008ee08ecc4873c109a5b">yarn</a>, <a href="https://gist.github.com/ijlee2/fba20304670b8d2b71f0b81cd07ea026">npm</a> </li> <li>Ember apps: <a href="https://gist.github.com/ijlee2/1c864ebe96a55f239e80800829ef0bf4">yarn</a>, <a href="https://gist.github.com/ijlee2/6576ae82895d522ccc0695518c2a6ce7">npm</a> </li> </ul> <p>If you are interested in cross-resolution testing, I recommend studying the <a href="https://github.com/ijlee2/ember-container-query/blob/main/.github/workflows/ci.yml">workflow for ember-container-query</a>.</p> ember javascript ci tutorial Isaac Lee Sun, 09 Aug 2020 11:07:15 +0000 https://dev.to/ijlee2/3-refactoring-techniques-2cai https://dev.to/ijlee2/3-refactoring-techniques-2cai <blockquote> <p><em>This mess was yours. Now your mess is mine.</em></p> <p>- Vance Joy</p> </blockquote> <p><a href="https://hacktoberfest.digitalocean.com/">Hacktoberfest</a> is coming up. If you're new to open source contribution and unsure how to help, may I suggest refactoring code? You can provide a fresh perspective to unclear code and discover ways to leave it better than you found.</p> <p>There are 3 refactoring techniques that I often practice:</p> <ul> <li>Rename things</li> <li>Remove nests</li> <li>Extract functions</li> </ul> <p>Knowing how to apply just these 3 can get you far. I'll explain what they mean and how I used them (or should have used them) in projects.</p> <h2> 1. Rename Things </h2> <p>The goal of this technique is to <strong>help people communicate through code</strong>.</p> <p>I remember this story from my college professor. She once had inherited code in which variables had been named after baseball players. Why? I can only imagine spite from an unhappy programmer.</p> <p>If you didn't understand right away what a variable, conditional, or function does, then there's a chance that someone else won't either. Once you do understand what it does and how it interplays with other code, please give it a better name.</p> <h3> a. Variables </h3> <p>A variable name, done right, explains purpose. In general, you will want to prefer fully-spelled words over truncated ones. This removes ambiguity and allows guessing when searching code by text.</p> <p>Here's a change that I made to <a href="https://github.com/ember-learn/whats-new-in-emberland">whats-new-in-emberland</a>, an app that helps <a href="https://blog.emberjs.com/tags/newsletter.html">The Ember Times</a> newsletter find who contributed to Ember repos.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// Before</span> <span class="kd">let</span> <span class="nx">conListUniq</span><span class="p">;</span> <span class="c1">// After</span> <span class="kd">let</span> <span class="nx">contributorsList</span><span class="p">;</span> </code></pre> </div> <p>Had I not mentioned to you that the app finds contributors, I think you would've had a hard time deciphering what "conList" in <code>conListUniq</code> means.</p> <p>A variable name can also explain type. For example, you can begin the name with <code>is</code> or <code>can</code> to indicate a boolean and pluralize the name to denote an array. Plural name comes in handy when you iterate over the array. You can use the singular noun for the array element.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="k">export</span> <span class="kd">function</span> <span class="nx">filterMerged</span><span class="p">(</span><span class="nx">pullRequests</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">pullRequests</span><span class="p">.</span><span class="nx">filter</span><span class="p">(</span><span class="nx">pullRequest</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="kd">const</span> <span class="p">{</span> <span class="nx">isMadeByUser</span><span class="p">,</span> <span class="nx">isMergedThisWeek</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">pullRequest</span><span class="p">;</span> <span class="k">return</span> <span class="nx">isMadeByUser</span> <span class="o">&amp;&amp;</span> <span class="nx">isMergedThisWeek</span><span class="p">;</span> <span class="p">});</span> <span class="p">}</span> </code></pre> </div> <p>Notice the naming conventions in the variables <code>pullRequests</code>, <code>pullRequest</code>, <code>isMadeByUser</code>, and <code>isMergedThisWeek</code>.</p> <h3> b. Conditionals </h3> <p>A conditional statement, since it is made up of dynamic values and language-specific syntax, can be tough to digest at once. This is more true for a compound conditional—two or more statements joined by the <code>&amp;&amp;</code> or <code>||</code> operator.</p> <p>To maintain conditionals, try creating temporary variables with a clear name. In general, each statement in a compound conditional should get its own variable. When you read the code aloud, it will sound almost natural.</p> <p>Some time ago, I added a feature to <a href="https://github.com/ember-codemods/ember-component-template-colocation-migrator">ember-component-template-colocation-migrator</a>. It runs in command line so I needed to support a couple of flags.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="kd">const</span> <span class="p">{</span> <span class="nx">argv</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="dl">'</span><span class="s1">yargs</span><span class="dl">'</span><span class="p">);</span> <span class="c1">// Allow passing the flag, -fs (flat) or -ns (nested), to specify component structure</span> <span class="kd">const</span> <span class="nx">changeToFlatStructure</span> <span class="o">=</span> <span class="nx">argv</span><span class="p">.</span><span class="nx">f</span> <span class="o">&amp;&amp;</span> <span class="nx">argv</span><span class="p">.</span><span class="nx">s</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">changeToNestedStructure</span> <span class="o">=</span> <span class="nx">argv</span><span class="p">.</span><span class="nx">n</span> <span class="o">&amp;&amp;</span> <span class="nx">argv</span><span class="p">.</span><span class="nx">s</span><span class="p">;</span> <span class="kd">let</span> <span class="nx">structure</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">flat</span><span class="dl">'</span><span class="p">;</span> <span class="k">if</span> <span class="p">(</span><span class="nx">changeToFlatStructure</span><span class="p">)</span> <span class="p">{</span> <span class="nx">structure</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">flat</span><span class="dl">'</span><span class="p">;</span> <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="nx">changeToNestedStructure</span><span class="p">)</span> <span class="p">{</span> <span class="nx">structure</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">nested</span><span class="dl">'</span><span class="p">;</span> <span class="p">}</span> </code></pre> </div> <p>Creating temporary variables has the benefit of abstraction. If we later decide to use a different library to handle flags, only lines 1-5 would change. The branching logic for <code>structure</code> can remain the same.</p> <h3> c. Functions </h3> <p>In Section 3, we will look at how functions play a critical role in refactoring.</p> <p>As for naming, I encourage you to start a function's name with a verb. I like to use <code>get</code> or <code>find</code> to indicate a function that retrieves data, and <code>set</code> or <code>update</code> to denote one that changes data.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="p">@</span><span class="nd">action</span> <span class="k">async</span> <span class="nx">getContributors</span><span class="p">()</span> <span class="p">{</span> <span class="kd">const</span> <span class="nx">fetchRequests</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">mergedPRs</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">pullRequest</span> <span class="o">=&gt;</span> <span class="nx">pullRequest</span><span class="p">.</span><span class="nx">user</span><span class="p">);</span> <span class="kd">let</span> <span class="nx">users</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">all</span><span class="p">(</span><span class="nx">fetchRequests</span><span class="p">);</span> <span class="nx">users</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">identifyUsers</span><span class="p">(</span><span class="nx">users</span><span class="p">);</span> <span class="nx">users</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">sortUsers</span><span class="p">(</span><span class="nx">users</span><span class="p">);</span> <span class="k">this</span><span class="p">.</span><span class="nx">updateContributorsList</span><span class="p">(</span><span class="nx">users</span><span class="p">);</span> <span class="p">}</span> </code></pre> </div> <p>Notice the use of verbs in <code>getContributors</code>, <code>identifyUsers</code>, <code>sortUsers</code>, and <code>updateContributorsList</code>. Although you don't see their implementation, you may be able to guess what each is supposed to do.</p> <h2> 2. Remove Nests </h2> <p>Removing nests is about <strong>flattening code structure</strong>. By removing indentations that are unnecessary, the ones that remain can clearly show groups of related code.</p> <p>Since code indentation is a bit of styling choice, you might wonder why removing nests matters. We'll look at nested conditionals and promises to see their drawbacks.</p> <h3> a. Nested Conditionals </h3> <p>Over time, a nested if statement can turn into mess. Business logic changes constantly. Pressured by time, we may add exceptions to allow new logic rather than refactor code in order to find a holistic solution.</p> <p>The best fictitious example comes from Sandi Metz's 2014 RailsConf talk, <a href="https://www.youtube.com/watch?v=8bZh5LMaSmE">All the Little Things</a>. Sandi talks of the <a href="https://github.com/NotMyself/GildedRose">Gilded Rose</a> problem. Given this code,<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight ruby"><code><span class="k">def</span> <span class="nf">tick</span> <span class="k">if</span> <span class="vi">@name</span> <span class="o">!=</span> <span class="s1">'Aged Brie'</span> <span class="o">&amp;&amp;</span> <span class="vi">@name</span> <span class="o">!=</span> <span class="s1">'Backstage passes to a TAFKAL80ETC concert'</span> <span class="k">if</span> <span class="vi">@quality</span> <span class="o">&gt;</span> <span class="mi">0</span> <span class="k">if</span> <span class="vi">@name</span> <span class="o">!=</span> <span class="s1">'Sulfuras, Hand of Ragnaros'</span> <span class="vi">@quality</span> <span class="o">-=</span> <span class="mi">1</span> <span class="k">end</span> <span class="k">end</span> <span class="k">else</span> <span class="k">if</span> <span class="vi">@quality</span> <span class="o">&lt;</span> <span class="mi">50</span> <span class="vi">@quality</span> <span class="o">+=</span> <span class="mi">1</span> <span class="k">if</span> <span class="vi">@name</span> <span class="o">==</span> <span class="s1">'Backstage passes to a TAFKAL80ETC concert'</span> <span class="k">if</span> <span class="vi">@days_remaining</span> <span class="o">&lt;</span> <span class="mi">11</span> <span class="k">if</span> <span class="vi">@quality</span> <span class="o">&lt;</span> <span class="mi">50</span> <span class="vi">@quality</span> <span class="o">+=</span> <span class="mi">1</span> <span class="k">end</span> <span class="k">end</span> <span class="k">if</span> <span class="vi">@days_remaining</span> <span class="o">&lt;</span> <span class="mi">6</span> <span class="k">if</span> <span class="vi">@quality</span> <span class="o">&lt;</span> <span class="mi">50</span> <span class="vi">@quality</span> <span class="o">+=</span> <span class="mi">1</span> <span class="k">end</span> <span class="k">end</span> <span class="k">end</span> <span class="k">end</span> <span class="k">end</span> <span class="k">if</span> <span class="vi">@name</span> <span class="o">!=</span> <span class="s1">'Sulfuras, Hand of Ragnaros'</span> <span class="vi">@days_remaining</span> <span class="o">-=</span> <span class="mi">1</span> <span class="k">end</span> <span class="k">if</span> <span class="vi">@days_remaining</span> <span class="o">&lt;</span> <span class="mi">0</span> <span class="k">if</span> <span class="vi">@name</span> <span class="o">!=</span> <span class="s1">'Aged Brie'</span> <span class="k">if</span> <span class="vi">@name</span> <span class="o">!=</span> <span class="s1">'Backstage passes to a TAFKAL80ETC concert'</span> <span class="k">if</span> <span class="vi">@quality</span> <span class="o">&gt;</span> <span class="mi">0</span> <span class="k">if</span> <span class="vi">@name</span> <span class="o">!=</span> <span class="s1">'Sulfuras, Hand of Ragnaros'</span> <span class="vi">@quality</span> <span class="o">-=</span> <span class="mi">1</span> <span class="k">end</span> <span class="k">end</span> <span class="k">else</span> <span class="vi">@quality</span> <span class="o">=</span> <span class="vi">@quality</span> <span class="o">-</span> <span class="vi">@quality</span> <span class="k">end</span> <span class="k">else</span> <span class="k">if</span> <span class="vi">@quality</span> <span class="o">&lt;</span> <span class="mi">50</span> <span class="vi">@quality</span> <span class="o">+=</span> <span class="mi">1</span> <span class="k">end</span> <span class="k">end</span> <span class="k">end</span> <span class="k">end</span> </code></pre> </div> <p>you are to update <code>tick</code> to handle just 1 more feature and ensure that all tests continue to pass. Where do you even begin?</p> <p>The key to refactoring <code>tick</code> is to <strong>make early exits</strong>, also called guard clauses. If you see code that can happen only when a condition is true, you leave immediately where you are (using <code>return</code>, <code>break</code>, or <code>continue</code>) if it evaluates to false.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// Before</span> <span class="kd">function</span> <span class="nx">myExample</span><span class="p">()</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="nx">condition</span><span class="p">)</span> <span class="p">{</span> <span class="cm">/* Complex code omitted */</span> <span class="p">}</span> <span class="p">}</span> <span class="c1">// After</span> <span class="kd">function</span> <span class="nx">myExample</span><span class="p">()</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">condition</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span><span class="p">;</span> <span class="p">}</span> <span class="cm">/* Complex code omitted */</span> <span class="p">}</span> </code></pre> </div> <p>Notice that we removed 1 indentation level from the complex code. Imagine you are able to make a few early exits. With each non-exit, the complex code can become simpler and allow other refactors. Moreover, by reading the series of <code>if</code> statements from top to bottom, you know exactly when the next code runs.</p> <p>Through a series of small refactors, Sandi arrives at the following code. I bet that you can more easily understand and change this code.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight ruby"><code><span class="k">def</span> <span class="nf">tick</span> <span class="k">case</span> <span class="nb">name</span> <span class="k">when</span> <span class="s1">'normal'</span> <span class="n">normal_tick</span> <span class="k">when</span> <span class="s1">'Aged Brie'</span> <span class="n">brie_tick</span> <span class="k">when</span> <span class="s1">'Sulfuras, Hand of Ragnaros'</span> <span class="n">sulfuras_tick</span> <span class="k">when</span> <span class="s1">'Backstage passes to a TAFKAL80ETC concert'</span> <span class="n">backstage_tick</span> <span class="k">end</span> <span class="k">end</span> <span class="k">def</span> <span class="nf">normal_tick</span> <span class="vi">@days_remaining</span> <span class="o">-=</span> <span class="mi">1</span> <span class="k">return</span> <span class="k">if</span> <span class="vi">@quality</span> <span class="o">==</span> <span class="mi">0</span> <span class="vi">@quality</span> <span class="o">-=</span> <span class="mi">1</span> <span class="vi">@quality</span> <span class="o">-=</span> <span class="mi">1</span> <span class="k">if</span> <span class="vi">@days_remaining</span> <span class="o">&lt;=</span> <span class="mi">0</span> <span class="k">end</span> <span class="k">def</span> <span class="nf">brie_tick</span> <span class="vi">@days_remaining</span> <span class="o">-=</span> <span class="mi">1</span> <span class="k">return</span> <span class="k">if</span> <span class="vi">@quality</span> <span class="o">&gt;=</span> <span class="mi">50</span> <span class="vi">@quality</span> <span class="o">+=</span> <span class="mi">1</span> <span class="vi">@quality</span> <span class="o">+=</span> <span class="mi">1</span> <span class="k">if</span> <span class="vi">@days_remaining</span> <span class="o">&lt;=</span> <span class="mi">0</span> <span class="k">end</span> <span class="k">def</span> <span class="nf">sulfuras_tick</span> <span class="k">end</span> <span class="k">def</span> <span class="nf">backstage_tick</span> <span class="vi">@days_remaining</span> <span class="o">-=</span> <span class="mi">1</span> <span class="k">return</span> <span class="k">if</span> <span class="vi">@quality</span> <span class="o">&gt;=</span> <span class="mi">50</span> <span class="k">return</span> <span class="vi">@quality</span> <span class="o">=</span> <span class="mi">0</span> <span class="k">if</span> <span class="vi">@days_remaining</span> <span class="o">&lt;</span> <span class="mi">0</span> <span class="vi">@quality</span> <span class="o">+=</span> <span class="mi">1</span> <span class="vi">@quality</span> <span class="o">+=</span> <span class="mi">1</span> <span class="k">if</span> <span class="vi">@days_remaining</span> <span class="o">&lt;</span> <span class="mi">10</span> <span class="vi">@quality</span> <span class="o">+=</span> <span class="mi">1</span> <span class="k">if</span> <span class="vi">@days_remaining</span> <span class="o">&lt;</span> <span class="mi">5</span> <span class="k">end</span> </code></pre> </div> <p>Let me defer my real-life example to Section 3c. I will show how to update the flags code from <a href="https://github.com/ember-codemods/ember-component-template-colocation-migrator">ember-component-template-colocation-migrator</a>.</p> <h3> b. Nested Promises </h3> <p>Previously, we saw that a nested if statement can be hard to reason and modify. By the same token, we want to avoid nested promises.</p> <p>Here's a server code that I had written in my nascent days:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="nx">router</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">/my-example</span><span class="dl">'</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">req</span><span class="p">,</span> <span class="nx">res</span><span class="p">)</span> <span class="p">{</span> <span class="nx">Writer</span><span class="p">.</span><span class="nx">findOne</span><span class="p">(</span><span class="cm">/* Query options omitted */</span><span class="p">)</span> <span class="p">.</span><span class="nx">then</span><span class="p">(</span><span class="nx">user</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="c1">// Get the user's profile</span> <span class="kd">const</span> <span class="nx">profile</span> <span class="o">=</span> <span class="nx">user</span><span class="p">.</span><span class="nx">dataValues</span><span class="p">;</span> <span class="c1">// Serialize the user's stories</span> <span class="kd">const</span> <span class="nx">stories</span> <span class="o">=</span> <span class="nx">user</span><span class="p">.</span><span class="nx">Stories</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">story</span> <span class="o">=&gt;</span> <span class="p">({</span> <span class="na">id</span><span class="p">:</span> <span class="nx">story</span><span class="p">.</span><span class="nx">id</span><span class="p">,</span> <span class="na">title</span><span class="p">:</span> <span class="nx">story</span><span class="p">.</span><span class="nx">title</span><span class="p">,</span> <span class="na">writer</span><span class="p">:</span> <span class="p">{</span> <span class="na">id</span><span class="p">:</span> <span class="nx">profile</span><span class="p">.</span><span class="nx">id</span><span class="p">,</span> <span class="na">fullName</span><span class="p">:</span> <span class="nx">profile</span><span class="p">.</span><span class="nx">fullName</span> <span class="p">},</span> <span class="na">photos</span><span class="p">:</span> <span class="nx">story</span><span class="p">.</span><span class="nx">Photos</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">photo</span> <span class="o">=&gt;</span> <span class="p">({</span> <span class="na">id</span><span class="p">:</span> <span class="nx">photo</span><span class="p">.</span><span class="nx">id</span><span class="p">,</span> <span class="na">url</span><span class="p">:</span> <span class="nx">photo</span><span class="p">.</span><span class="nx">url</span><span class="p">,</span> <span class="na">caption</span><span class="p">:</span> <span class="nx">photo</span><span class="p">.</span><span class="nx">caption</span> <span class="p">}))</span> <span class="p">}));</span> <span class="c1">// Serialize the user's readers</span> <span class="kd">const</span> <span class="nx">readers</span> <span class="o">=</span> <span class="nx">user</span><span class="p">.</span><span class="nx">Readers</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">reader</span> <span class="o">=&gt;</span> <span class="p">({</span> <span class="na">readerId</span><span class="p">:</span> <span class="nx">reader</span><span class="p">.</span><span class="nx">reader_id</span> <span class="p">}));</span> <span class="c1">// Serialize the user's writers</span> <span class="nx">Reader</span><span class="p">.</span><span class="nx">findAll</span><span class="p">(</span><span class="cm">/* Query options omitted */</span><span class="p">)</span> <span class="p">.</span><span class="nx">then</span><span class="p">(</span><span class="nx">results</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="kd">const</span> <span class="nx">writers</span> <span class="o">=</span> <span class="nx">results</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">writer</span> <span class="o">=&gt;</span> <span class="p">({</span> <span class="na">writerId</span><span class="p">:</span> <span class="nx">writer</span><span class="p">.</span><span class="nx">writer_id</span> <span class="p">}));</span> <span class="c1">// Send the user's profile, stories, readers, and writers</span> <span class="nx">res</span><span class="p">.</span><span class="nx">json</span><span class="p">({</span> <span class="nx">profile</span><span class="p">,</span> <span class="nx">stories</span><span class="p">,</span> <span class="nx">readers</span><span class="p">,</span> <span class="nx">writers</span> <span class="p">});</span> <span class="p">});</span> <span class="p">});</span> <span class="p">});</span> </code></pre> </div> <p>The end goal is remarkably simple: Send to a client what we know about the user (lines 35-40). So why does the code feel like mess?</p> <p>One reason is nested promises. (There's another and we will address it in Section 3a.) With so many indentations, it's difficult to see where code begins and ends, and which variables cross over from one promise to another. In addition, the code assumes no failure points.</p> <p>Prior to the wide adoption of <code>async</code> and <code>await</code>, we might have used a promise chain to refactor this code. <a href="https://philipwalton.com/articles/untangling-deeply-nested-promise-chains/">A promise chain isn't without problems</a>, however.</p> <p>Using <code>async</code> and <code>await</code>, we can rewrite the code as follows:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="nx">router</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">/my-example</span><span class="dl">'</span><span class="p">,</span> <span class="k">async</span> <span class="kd">function</span><span class="p">(</span><span class="nx">req</span><span class="p">,</span> <span class="nx">res</span><span class="p">)</span> <span class="p">{</span> <span class="k">try</span> <span class="p">{</span> <span class="kd">const</span> <span class="nx">user</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">Writer</span><span class="p">.</span><span class="nx">findOne</span><span class="p">(</span><span class="cm">/* Query options omitted */</span><span class="p">);</span> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">user</span><span class="p">)</span> <span class="p">{</span> <span class="k">throw</span> <span class="k">new</span> <span class="nb">Error</span><span class="p">(</span><span class="dl">'</span><span class="s1">Could not find user.</span><span class="dl">'</span><span class="p">);</span> <span class="p">}</span> <span class="c1">// Get user's profile</span> <span class="kd">const</span> <span class="nx">profile</span> <span class="o">=</span> <span class="nx">user</span><span class="p">.</span><span class="nx">dataValues</span><span class="p">;</span> <span class="c1">// Serialize user's stories</span> <span class="kd">const</span> <span class="nx">stories</span> <span class="o">=</span> <span class="nx">user</span><span class="p">.</span><span class="nx">Stories</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">story</span> <span class="o">=&gt;</span> <span class="p">({</span> <span class="na">id</span><span class="p">:</span> <span class="nx">story</span><span class="p">.</span><span class="nx">id</span><span class="p">,</span> <span class="na">title</span><span class="p">:</span> <span class="nx">story</span><span class="p">.</span><span class="nx">title</span><span class="p">,</span> <span class="na">writer</span><span class="p">:</span> <span class="p">{</span> <span class="na">id</span><span class="p">:</span> <span class="nx">profile</span><span class="p">.</span><span class="nx">id</span><span class="p">,</span> <span class="na">fullName</span><span class="p">:</span> <span class="nx">profile</span><span class="p">.</span><span class="nx">fullName</span> <span class="p">},</span> <span class="na">photos</span><span class="p">:</span> <span class="nx">story</span><span class="p">.</span><span class="nx">Photos</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">photo</span> <span class="o">=&gt;</span> <span class="p">({</span> <span class="na">id</span><span class="p">:</span> <span class="nx">photo</span><span class="p">.</span><span class="nx">id</span><span class="p">,</span> <span class="na">url</span><span class="p">:</span> <span class="nx">photo</span><span class="p">.</span><span class="nx">url</span><span class="p">,</span> <span class="na">caption</span><span class="p">:</span> <span class="nx">photo</span><span class="p">.</span><span class="nx">caption</span> <span class="p">}))</span> <span class="p">}));</span> <span class="c1">// Serialize user's readers</span> <span class="kd">const</span> <span class="nx">readers</span> <span class="o">=</span> <span class="nx">user</span><span class="p">.</span><span class="nx">Readers</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">reader</span> <span class="o">=&gt;</span> <span class="p">({</span> <span class="na">readerId</span><span class="p">:</span> <span class="nx">reader</span><span class="p">.</span><span class="nx">reader_id</span> <span class="p">}));</span> <span class="c1">// Serialize user's writers</span> <span class="kd">const</span> <span class="nx">results</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">Reader</span><span class="p">.</span><span class="nx">findAll</span><span class="p">(</span><span class="cm">/* Query options omitted */</span><span class="p">);</span> <span class="kd">const</span> <span class="nx">writers</span> <span class="o">=</span> <span class="nx">results</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">writer</span> <span class="o">=&gt;</span> <span class="p">({</span> <span class="na">writerId</span><span class="p">:</span> <span class="nx">writer</span><span class="p">.</span><span class="nx">writer_id</span> <span class="p">}));</span> <span class="c1">// Send the user's profile, stories, readers, and writers</span> <span class="nx">res</span><span class="p">.</span><span class="nx">json</span><span class="p">({</span> <span class="nx">profile</span><span class="p">,</span> <span class="nx">stories</span><span class="p">,</span> <span class="nx">readers</span><span class="p">,</span> <span class="nx">writers</span> <span class="p">});</span> <span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span> <span class="cm">/* Error handling omitted */</span> <span class="p">}</span> <span class="p">});</span> </code></pre> </div> <p>Notice that <code>profile</code>, <code>stories</code>, <code>readers</code>, and <code>writers</code> are now defined at the same indentation level. This helps us trace the ending of the story that the code tells. In the end, we send data to the client, but where do they come from? Let's scroll up.</p> <h2> 3. Extract Functions </h2> <p>Now for the grand finale. At times, you may encounter a function that does 1 thing (this is good) but has many lines of code (likely bad). In fact, you saw one in Section 2b.</p> <p>The function contains a few key steps that run in sequence. Your goals are to:</p> <ul> <li>Identify the key steps</li> <li>Create a function for each step</li> <li>Assign each function a descriptive name</li> </ul> <p>This process of <strong>breaking a large function into smaller ones</strong> is called extraction. Some of the smaller functions, especially if they don't require talking to an external system (e.g. make an API request or search an index), can now be unit-tested.</p> <p>If I were to pick the most useful refactoring technique, extraction would be it.</p> <h3> a. Example 1 </h3> <p>In Section 2b, we managed to remove nested promises. Let's refactor the code further by extracting functions.</p> <p>How do you identify the key steps? A good indicator is a comment that was left to describe what the code does. You may even name the function based on the comment.</p> <p>If I got to rewrite the API, I think it would look something like this:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="k">import</span> <span class="p">{</span> <span class="nx">serialize</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">../some-path</span><span class="dl">'</span><span class="p">;</span> <span class="nx">router</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">/my-example</span><span class="dl">'</span><span class="p">,</span> <span class="k">async</span> <span class="kd">function</span><span class="p">(</span><span class="nx">req</span><span class="p">,</span> <span class="nx">res</span><span class="p">)</span> <span class="p">{</span> <span class="k">try</span> <span class="p">{</span> <span class="kd">const</span> <span class="nx">user</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">Writer</span><span class="p">.</span><span class="nx">findOne</span><span class="p">(</span><span class="cm">/* query options omitted */</span><span class="p">);</span> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">user</span><span class="p">)</span> <span class="p">{</span> <span class="k">throw</span> <span class="k">new</span> <span class="nb">Error</span><span class="p">(</span><span class="dl">'</span><span class="s1">Could not find user.</span><span class="dl">'</span><span class="p">);</span> <span class="p">}</span> <span class="kd">const</span> <span class="nx">profile</span> <span class="o">=</span> <span class="nx">getProfile</span><span class="p">(</span><span class="nx">user</span><span class="p">);</span> <span class="kd">const</span> <span class="nx">stories</span> <span class="o">=</span> <span class="nx">serialize</span><span class="p">({</span> <span class="na">name</span><span class="p">:</span> <span class="dl">'</span><span class="s1">Story</span><span class="dl">'</span><span class="p">,</span> <span class="na">data</span><span class="p">:</span> <span class="nx">user</span><span class="p">.</span><span class="nx">Stories</span> <span class="p">});</span> <span class="kd">const</span> <span class="nx">readers</span> <span class="o">=</span> <span class="nx">serialize</span><span class="p">({</span> <span class="na">name</span><span class="p">:</span> <span class="dl">'</span><span class="s1">Reader</span><span class="dl">'</span><span class="p">,</span> <span class="na">data</span><span class="p">:</span> <span class="nx">user</span><span class="p">.</span><span class="nx">Readers</span> <span class="p">});</span> <span class="kd">const</span> <span class="nx">writers</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">getWriters</span><span class="p">(</span><span class="nx">user</span><span class="p">);</span> <span class="nx">res</span><span class="p">.</span><span class="nx">json</span><span class="p">({</span> <span class="nx">profile</span><span class="p">,</span> <span class="nx">stories</span><span class="p">,</span> <span class="nx">readers</span><span class="p">,</span> <span class="nx">writers</span> <span class="p">});</span> <span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span> <span class="cm">/* Handle error */</span> <span class="p">}</span> <span class="p">});</span> <span class="kd">function</span> <span class="nx">getProfile</span><span class="p">(</span><span class="nx">user</span><span class="p">)</span> <span class="p">{</span><span class="cm">/* ... */</span><span class="p">}</span> <span class="k">async</span> <span class="kd">function</span> <span class="nx">getWriters</span><span class="p">(</span><span class="nx">user</span><span class="p">)</span> <span class="p">{</span><span class="cm">/* ... */</span><span class="p">}</span> </code></pre> </div> <h3> b. Example 2 </h3> <p>In <a href="https://github.com/ember-learn/whats-new-in-emberland">whats-new-in-emberland</a>, I found the <code>model</code> hook, a function that fetches PRs (pull requests) and RFCs (requests for comments), looking like this:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="k">async</span> <span class="nx">model</span><span class="p">()</span> <span class="p">{</span> <span class="kd">const</span> <span class="nx">store</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">store</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">startOfWeek</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">startOfWeek</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">projectFetches</span> <span class="o">=</span> <span class="nx">CONSTANTS</span><span class="p">.</span><span class="nx">REPOS</span><span class="p">.</span><span class="nx">map</span><span class="p">((</span><span class="nx">repo</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">store</span><span class="p">.</span><span class="nx">findRecord</span><span class="p">(</span><span class="dl">'</span><span class="s1">github-organization</span><span class="dl">'</span><span class="p">,</span> <span class="nx">repo</span><span class="p">);</span> <span class="p">});</span> <span class="kd">let</span> <span class="nx">orgs</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">all</span><span class="p">(</span><span class="nx">projectFetches</span><span class="p">);</span> <span class="kd">const</span> <span class="nx">prFetches</span> <span class="o">=</span> <span class="nx">orgs</span><span class="p">.</span><span class="nx">map</span><span class="p">((</span><span class="nx">org</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">fetch</span><span class="p">(</span><span class="s2">`https://api.github.com/search/issues?q=is:pr+org:</span><span class="p">${</span><span class="nx">org</span><span class="p">.</span><span class="nx">id</span><span class="p">}</span><span class="s2">+created:&gt;=</span><span class="p">${</span><span class="nx">moment</span><span class="p">(</span><span class="nx">startOfWeek</span><span class="p">).</span><span class="nx">format</span><span class="p">(</span><span class="dl">'</span><span class="s1">YYYY-MM-DD</span><span class="dl">'</span><span class="p">)}</span><span class="s2">`</span><span class="p">,</span> <span class="p">{</span> <span class="na">headers</span><span class="p">:</span> <span class="p">{</span> <span class="dl">'</span><span class="s1">Authorization</span><span class="dl">'</span><span class="p">:</span> <span class="s2">`token </span><span class="p">${</span><span class="k">this</span><span class="p">.</span><span class="nx">githubSession</span><span class="p">.</span><span class="nx">githubAccessToken</span><span class="p">}</span><span class="s2">`</span><span class="p">,</span> <span class="p">},</span> <span class="p">})</span> <span class="p">.</span><span class="nx">then</span><span class="p">((</span><span class="nx">response</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">response</span><span class="p">.</span><span class="nx">json</span><span class="p">())</span> <span class="p">.</span><span class="nx">then</span><span class="p">((</span><span class="nx">pulls</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="k">this</span><span class="p">.</span><span class="nx">store</span><span class="p">.</span><span class="nx">pushPayload</span><span class="p">(</span><span class="dl">'</span><span class="s1">github-pull</span><span class="dl">'</span><span class="p">,</span> <span class="p">{</span> <span class="na">githubPull</span><span class="p">:</span> <span class="nx">pulls</span><span class="p">.</span><span class="nx">items</span> <span class="p">}));</span> <span class="p">});</span> <span class="kd">const</span> <span class="nx">rfcFetches</span> <span class="o">=</span> <span class="p">[</span><span class="dl">'</span><span class="s1">ember-cli/rfcs</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">emberjs/rfcs</span><span class="dl">'</span><span class="p">].</span><span class="nx">map</span><span class="p">((</span><span class="nx">repo</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">store</span><span class="p">.</span><span class="nx">query</span><span class="p">(</span><span class="dl">'</span><span class="s1">github-pull</span><span class="dl">'</span><span class="p">,</span> <span class="p">{</span> <span class="nx">repo</span><span class="p">,</span> <span class="na">state</span><span class="p">:</span> <span class="dl">'</span><span class="s1">all</span><span class="dl">'</span> <span class="p">});</span> <span class="p">});</span> <span class="k">await</span> <span class="nx">all</span><span class="p">(</span><span class="nx">prFetches</span><span class="p">);</span> <span class="kd">let</span> <span class="nx">pulls</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">store</span><span class="p">.</span><span class="nx">peekAll</span><span class="p">(</span><span class="dl">'</span><span class="s1">github-pull</span><span class="dl">'</span><span class="p">).</span><span class="nx">toArray</span><span class="p">();</span> <span class="kd">let</span> <span class="nx">rfcSets</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">all</span><span class="p">(</span><span class="nx">rfcFetches</span><span class="p">);</span> <span class="kd">let</span> <span class="nx">mergedPulls</span> <span class="o">=</span> <span class="nx">pulls</span><span class="p">.</span><span class="nx">filter</span><span class="p">((</span><span class="nx">pull</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">moment</span><span class="p">(</span><span class="nx">pull</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">mergedAt</span><span class="dl">'</span><span class="p">))</span> <span class="o">&gt;</span> <span class="nx">moment</span><span class="p">(</span><span class="nx">startOfWeek</span><span class="p">);</span> <span class="p">}).</span><span class="nx">reduce</span><span class="p">((</span><span class="nx">previousValue</span><span class="p">,</span> <span class="nx">item</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">previousValue</span><span class="p">.</span><span class="nx">concat</span><span class="p">(</span><span class="nx">item</span><span class="p">),</span> <span class="p">[]);</span> <span class="kd">let</span> <span class="nx">newPulls</span> <span class="o">=</span> <span class="nx">pulls</span><span class="p">.</span><span class="nx">filter</span><span class="p">((</span><span class="nx">pull</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">moment</span><span class="p">(</span><span class="nx">pull</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">createdAt</span><span class="dl">'</span><span class="p">))</span> <span class="o">&gt;</span> <span class="nx">moment</span><span class="p">(</span><span class="nx">startOfWeek</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="o">!</span><span class="nx">pull</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">mergedAt</span><span class="dl">'</span><span class="p">);</span> <span class="p">}).</span><span class="nx">reduce</span><span class="p">((</span><span class="nx">previousValue</span><span class="p">,</span> <span class="nx">item</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">previousValue</span><span class="p">.</span><span class="nx">concat</span><span class="p">(</span><span class="nx">item</span><span class="p">),</span> <span class="p">[]);</span> <span class="kd">let</span> <span class="nx">newRfcs</span> <span class="o">=</span> <span class="nx">rfcSets</span><span class="p">.</span><span class="nx">map</span><span class="p">((</span><span class="nx">pulls</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">pulls</span><span class="p">.</span><span class="nx">filter</span><span class="p">((</span><span class="nx">pull</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">moment</span><span class="p">(</span><span class="nx">pull</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">createdAt</span><span class="dl">'</span><span class="p">))</span> <span class="o">&gt;</span> <span class="nx">moment</span><span class="p">(</span><span class="nx">startOfWeek</span><span class="p">);</span> <span class="p">});</span> <span class="p">}).</span><span class="nx">reduce</span><span class="p">((</span><span class="nx">previousValue</span><span class="p">,</span> <span class="nx">item</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">previousValue</span><span class="p">.</span><span class="nx">concat</span><span class="p">(</span><span class="nx">item</span><span class="p">),</span> <span class="p">[]);</span> <span class="kd">let</span> <span class="nx">mergedRfcs</span> <span class="o">=</span> <span class="nx">rfcSets</span><span class="p">.</span><span class="nx">map</span><span class="p">((</span><span class="nx">pulls</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">pulls</span><span class="p">.</span><span class="nx">filter</span><span class="p">((</span><span class="nx">pull</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">moment</span><span class="p">(</span><span class="nx">pull</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">mergedAt</span><span class="dl">'</span><span class="p">))</span> <span class="o">&gt;</span> <span class="nx">moment</span><span class="p">(</span><span class="nx">startOfWeek</span><span class="p">);</span> <span class="p">});</span> <span class="p">}).</span><span class="nx">reduce</span><span class="p">((</span><span class="nx">previousValue</span><span class="p">,</span> <span class="nx">item</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">previousValue</span><span class="p">.</span><span class="nx">concat</span><span class="p">(</span><span class="nx">item</span><span class="p">),</span> <span class="p">[]);</span> <span class="k">return</span> <span class="nx">hash</span><span class="p">({</span> <span class="nx">orgs</span><span class="p">,</span> <span class="nx">mergedPulls</span><span class="p">,</span> <span class="nx">newPulls</span><span class="p">,</span> <span class="nx">mergedRfcs</span><span class="p">,</span> <span class="nx">newRfcs</span> <span class="p">});</span> <span class="p">}</span> </code></pre> </div> <p>The key to refactoring <code>model</code> was to extract functions one at a time. From lines 5-19 and 25-26, I understood that <code>model</code> fetches PRs. That's great! I <a href="https://github.com/ember-learn/whats-new-in-emberland/pull/43/commits/446d4edd3444ccd151e38629eeab2715a073b61e">extracted a function</a>. Similarly, from lines 21-23 and 27, I saw that <code>model</code> fetches RFCs. That's yet another <a href="https://github.com/ember-learn/whats-new-in-emberland/pull/43/commits/9efac8bd0199b8887930aad8542099bef7670ef1">extraction</a>.</p> <p>It was interesting that extracting functions from lines 29-47 (a total of 4 functions) did require knowledge of Ember in order to refactor effectively. In addition to the <code>model</code> hook, Ember provides the <code>setupController</code> hook. It allows us to post-process data from <code>model</code>. For example, we can filter arrays.</p> <p>I moved lines 29-47 to <code>setupController</code> for better separation of concerns, extracted functions, then further simplified code. In the end, I uncovered this beautiful code:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="nx">model</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">hash</span><span class="p">({</span> <span class="na">prs</span><span class="p">:</span> <span class="k">this</span><span class="p">.</span><span class="nx">fetchPRs</span><span class="p">(),</span> <span class="na">rfcs</span><span class="p">:</span> <span class="k">this</span><span class="p">.</span><span class="nx">fetchRFCs</span><span class="p">()</span> <span class="p">});</span> <span class="p">}</span> <span class="nx">setupController</span><span class="p">(</span><span class="nx">controller</span><span class="p">,</span> <span class="nx">model</span><span class="p">)</span> <span class="p">{</span> <span class="k">super</span><span class="p">.</span><span class="nx">setupController</span><span class="p">(</span><span class="nx">controller</span><span class="p">,</span> <span class="nx">model</span><span class="p">);</span> <span class="kd">const</span> <span class="p">{</span> <span class="nx">prs</span><span class="p">,</span> <span class="nx">rfcs</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">model</span><span class="p">;</span> <span class="nx">controller</span><span class="p">.</span><span class="nx">mergedPRs</span> <span class="o">=</span> <span class="nx">filterMerged</span><span class="p">(</span><span class="nx">prs</span><span class="p">);</span> <span class="nx">controller</span><span class="p">.</span><span class="nx">newPRs</span> <span class="o">=</span> <span class="nx">filterNew</span><span class="p">(</span><span class="nx">prs</span><span class="p">);</span> <span class="nx">controller</span><span class="p">.</span><span class="nx">mergedRFCs</span> <span class="o">=</span> <span class="nx">filterMerged</span><span class="p">(</span><span class="nx">rfcs</span><span class="p">);</span> <span class="nx">controller</span><span class="p">.</span><span class="nx">newRFCs</span> <span class="o">=</span> <span class="nx">filterNew</span><span class="p">(</span><span class="nx">rfcs</span><span class="p">);</span> <span class="p">}</span> </code></pre> </div> <h3> c. Example 3 </h3> <p>In <a href="https://github.com/ember-codemods/ember-component-template-colocation-migrator">ember-component-template-colocation-migrator</a>, I <a href="https://github.com/ember-codemods/ember-component-template-colocation-migrator/pull/11/files/590a2b1754fad5c5b69974bdb0f4dbc4ff8ab2b8..e264611827ea39fb0028412dbece6e156789dd16">extracted a few functions</a> from the main function, <code>execute</code>, before I added a feature. As a result, the feature caused a small, predictable change to <code>execute</code> (lines 9-10 below):<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="k">async</span> <span class="nx">execute</span><span class="p">()</span> <span class="p">{</span> <span class="kd">let</span> <span class="nx">templateFilePaths</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">findClassicComponentTemplates</span><span class="p">();</span> <span class="nx">templateFilePaths</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">skipTemplatesUsedAsLayoutName</span><span class="p">(</span><span class="nx">templateFilePaths</span><span class="p">);</span> <span class="nx">templateFilePaths</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">skipTemplatesUsedAsPartial</span><span class="p">(</span><span class="nx">templateFilePaths</span><span class="p">);</span> <span class="k">if</span> <span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">structure</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">flat</span><span class="dl">'</span><span class="p">)</span> <span class="p">{</span> <span class="k">this</span><span class="p">.</span><span class="nx">changeComponentStructureToFlat</span><span class="p">(</span><span class="nx">templateFilePaths</span><span class="p">);</span> <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">structure</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">nested</span><span class="dl">'</span><span class="p">)</span> <span class="p">{</span> <span class="k">this</span><span class="p">.</span><span class="nx">changeComponentStructureToNested</span><span class="p">(</span><span class="nx">templateFilePaths</span><span class="p">);</span> <span class="p">}</span> <span class="k">await</span> <span class="k">this</span><span class="p">.</span><span class="nx">removeEmptyClassicComponentDirectories</span><span class="p">();</span> <span class="p">}</span> </code></pre> </div> <p>Another example—one that hasn't been done (it's up for grabs for Hacktoberfest!)—is to extract a function from the flags code that we saw earlier:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="kd">const</span> <span class="p">{</span> <span class="nx">argv</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="dl">'</span><span class="s1">yargs</span><span class="dl">'</span><span class="p">);</span> <span class="kd">function</span> <span class="nx">getStructure</span><span class="p">()</span> <span class="p">{</span> <span class="kd">const</span> <span class="nx">changeToFlatStructure</span> <span class="o">=</span> <span class="nx">argv</span><span class="p">.</span><span class="nx">f</span> <span class="o">&amp;&amp;</span> <span class="nx">argv</span><span class="p">.</span><span class="nx">s</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">changeToNestedStructure</span> <span class="o">=</span> <span class="nx">argv</span><span class="p">.</span><span class="nx">n</span> <span class="o">&amp;&amp;</span> <span class="nx">argv</span><span class="p">.</span><span class="nx">s</span><span class="p">;</span> <span class="k">if</span> <span class="p">(</span><span class="nx">changeToFlatStructure</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="dl">'</span><span class="s1">flat</span><span class="dl">'</span><span class="p">;</span> <span class="p">}</span> <span class="k">if</span> <span class="p">(</span><span class="nx">changeToNestedStructure</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="dl">'</span><span class="s1">nested</span><span class="dl">'</span><span class="p">;</span> <span class="p">}</span> <span class="k">return</span> <span class="dl">'</span><span class="s1">flat</span><span class="dl">'</span><span class="p">;</span> <span class="p">}</span> </code></pre> </div> <p>Notice the early exits, the refactoring technique that we learned in Section 2.</p> <h2> 4. Conclusion </h2> <p>You can make an impact on an open source project by refactoring code. By practicing just 3 techniques—<strong>rename things, remove nests, and extract functions</strong>—you can help new contributors understand code and increase the longevity of the project.</p> <p>You witnessed a few examples of what code can be like when you take good care of it. I encourage you to apply what you learned and share these techniques with others.</p> javascript tutorial beginners ember Isaac Lee Mon, 08 Jun 2020 13:07:49 +0000 https://dev.to/ijlee2/container-queries-cross-resolution-testing-jh8 https://dev.to/ijlee2/container-queries-cross-resolution-testing-jh8 <p><em>Originally published on <a href="https://crunchingnumbers.live" rel="noopener noreferrer">crunchingnumbers.live</a></em></p> <p><em>Failure</em> to test is why I started to work on <a href="https://github.com/ijlee2/ember-container-query/" rel="noopener noreferrer">ember-container-query</a>.</p> <p>A few months ago, my team and I introduced <a href="https://github.com/chadian/ember-fill-up" rel="noopener noreferrer">ember-fill-up</a> to our apps. It worked well but we noticed something strange. Percy snapshots that were taken at a mobile width would show <code>ember-fill-up</code> using the desktop breakpoint. They didn't match what we were seeing on our browsers.</p> <p>For a while, we ignored this issue because our CSS wasn't great. We performed some tricks with <code>flex</code> and <code>position</code> that could have affected Percy snapshots. Guess what happened when we switched to <code>grid</code> and improved the document flow. We still saw incorrect Percy snapshots.</p> <h2> 1. Whodunit? ember-qunit. </h2> <p>To eliminate <code>ember-fill-up</code> as a suspect, I used modifiers to recreate the addon. To my surprise and distress, using modifiers didn't fix the problem. After many trial-and-errors, I found the culprit: <code>ember-qunit</code>.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2020%2F06%2Fmeme-1.jpg" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2020%2F06%2Fmeme-1.jpg" alt=""></a></p> TIL Morpheus never said "What if I told you." Were the past 20 years real? <p>By default, <code>ember-qunit</code> <a href="https://github.com/emberjs/ember-qunit/blob/master/vendor/ember-qunit/test-container-styles.css#L32-L37" rel="noopener noreferrer">scales the test window</a> so that your app fits inside its test container.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight css"><code><span class="nf">#ember-testing</span> <span class="p">{</span> <span class="nl">width</span><span class="p">:</span> <span class="m">200%</span><span class="p">;</span> <span class="nl">height</span><span class="p">:</span> <span class="m">200%</span><span class="p">;</span> <span class="nl">transform</span><span class="p">:</span> <span class="n">scale</span><span class="p">(</span><span class="m">0.5</span><span class="p">);</span> <span class="nl">transform-origin</span><span class="p">:</span> <span class="nb">top</span> <span class="nb">left</span><span class="p">;</span> <span class="p">}</span> </code></pre> </div> <p>What does this mean? When you write tests, you cannot trust DOM render decisions that are based on width or height. Decisions made by media queries and addons like <code>ember-container-query</code>, <code>ember-fill-up</code>, <code>ember-responsive</code>, and <code>ember-screen</code>. Because what your test saw differed from what you saw on a browser, you might have had to mock a service (fake the window size) to get certain elements to (dis)appear.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2020%2F06%2Ftest-comparisons.jpg" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fcrunchingnumbersdotlive.files.wordpress.com%2F2020%2F06%2Ftest-comparisons.jpg" alt=""></a></p> Percy snapshots on top row are what we get with default <code>ember-qunit</code>. The snapshots on the middle row are what we want. There seem to be larger differences in smaller windows. (<a href="https://crunchingnumbersdotlive.files.wordpress.com/2020/06/test-comparisons.jpg" rel="noreferrer noopener">Full screen image</a>) <p>Fortunately, there is an <a href="https://github.com/emberjs/ember-qunit/blob/master/vendor/ember-qunit/test-container-styles.css#L39-L44" rel="noopener noreferrer">escape hatch</a>. We can apply the <code>.full-screen</code> class to the test container (<code>#ember-testing-container</code>) to undo the scaling.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight css"><code><span class="nc">.full-screen</span> <span class="nf">#ember-testing</span> <span class="p">{</span> <span class="nl">position</span><span class="p">:</span> <span class="nb">absolute</span><span class="p">;</span> <span class="nl">width</span><span class="p">:</span> <span class="m">100%</span><span class="p">;</span> <span class="nl">height</span><span class="p">:</span> <span class="m">100%</span><span class="p">;</span> <span class="nl">transform</span><span class="p">:</span> <span class="n">scale</span><span class="p">(</span><span class="m">1</span><span class="p">);</span> <span class="p">}</span> </code></pre> </div> <p>As an aside, this class is applied when we enable <a href="https://github.com/ember-cli/ember-cli-qunit/pull/120" rel="noopener noreferrer">development mode</a>, a relatively unknown feature.</p> <p>In my opinion and conjecture, we (Ember community) didn't really notice this problem and fix it because we were used to writing tests only at 1 resolution: the 1440 × 900 px desktop. We are also prone to designing the web for desktop first. Had we been able to test multiple resolutions easily, I think today's state of testing would be even better.</p> <h2> 2. Cross-Resolution Testing </h2> <p>How can you test your app and addon at multiple resolutions?</p> <p>We need to be able to mark tests that can only be run at one resolution. After all, there will be user workflows that make sense only on mobile or tablet, for example. My team and I followed the Octane craze and introduced <strong>filters</strong> that look like decorators:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// Mobile only</span> <span class="nf">test</span><span class="p">(</span><span class="dl">'</span><span class="s1">@mobile A user can do X in Dashboard</span><span class="dl">'</span><span class="p">);</span> <span class="c1">// Tablet only</span> <span class="nf">test</span><span class="p">(</span><span class="dl">'</span><span class="s1">@tablet A user can do X in Dashboard</span><span class="dl">'</span><span class="p">);</span> <span class="c1">// Any resolution</span> <span class="nf">test</span><span class="p">(</span><span class="dl">'</span><span class="s1">A user can do X in Dashboard</span><span class="dl">'</span><span class="p">);</span> </code></pre> </div> <p>Let's go over how to update your test setup, configure CI, and write a Percy test helper to allow these filters.</p> <p>I'll use <a href="https://crunchingnumbers.live/2020/03/17/ci-with-github-actions-for-ember-apps/" rel="noopener noreferrer">GitHub Actions for CI</a>. Describing each line of code can get boring so I'll convey the idea and simplify code in many cases. I encourage you to look at <a href="https://crunchingnumbers.live/2020/03/17/ci-with-github-actions-for-ember-apps/" rel="noopener noreferrer">ember-container-query</a> to study details and use my latest code.</p> <h3> a. testem.js </h3> <p>We'll start by updating <code>testem.js</code>. It is responsible for setting the window size.</p> <p>The idea is to dynamically set the window size based on an environment variable. I'll call this variable <code>DEVICE</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="kd">const</span> <span class="nx">FILTERS</span> <span class="o">=</span> <span class="p">{</span> <span class="na">mobile</span><span class="p">:</span> <span class="dl">'</span><span class="s1">/^(?=(.*Acceptance))(?!(.*@tablet|.*@desktop))/</span><span class="dl">'</span><span class="p">,</span> <span class="na">tablet</span><span class="p">:</span> <span class="dl">'</span><span class="s1">/^(?=(.*Acceptance))(?!(.*@mobile|.*@desktop))/</span><span class="dl">'</span><span class="p">,</span> <span class="na">desktop</span><span class="p">:</span> <span class="dl">'</span><span class="s1">/^(?!(.*@mobile|.*@tablet))/</span><span class="dl">'</span> <span class="p">};</span> <span class="kd">const</span> <span class="nx">WINDOW_SIZES</span> <span class="o">=</span> <span class="p">{</span> <span class="na">mobile</span><span class="p">:</span> <span class="dl">'</span><span class="s1">400,900</span><span class="dl">'</span><span class="p">,</span> <span class="na">tablet</span><span class="p">:</span> <span class="dl">'</span><span class="s1">900,900</span><span class="dl">'</span><span class="p">,</span> <span class="na">desktop</span><span class="p">:</span> <span class="dl">'</span><span class="s1">1400,900</span><span class="dl">'</span> <span class="p">};</span> <span class="kd">const</span> <span class="p">{</span> <span class="nx">DEVICE</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">desktop</span><span class="dl">'</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">process</span><span class="p">.</span><span class="nx">env</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">filter</span> <span class="o">=</span> <span class="nf">encodeURIComponent</span><span class="p">(</span><span class="nx">FILTERS</span><span class="p">[</span><span class="nx">DEVICE</span><span class="p">]);</span> <span class="kd">const</span> <span class="nx">windowSize</span> <span class="o">=</span> <span class="nx">WINDOW_SIZES</span><span class="p">[</span><span class="nx">DEVICE</span><span class="p">];</span> <span class="kd">const</span> <span class="p">[</span><span class="nx">width</span><span class="p">,</span> <span class="nx">height</span><span class="p">]</span> <span class="o">=</span> <span class="nx">windowSize</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="dl">'</span><span class="s1">,</span><span class="dl">'</span><span class="p">);</span> <span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="p">{</span> <span class="na">test_page</span><span class="p">:</span> <span class="s2">`tests/index.html?filter=</span><span class="p">${</span><span class="nx">filter</span><span class="p">}</span><span class="s2">&amp;amp;width=</span><span class="p">${</span><span class="nx">width</span><span class="p">}</span><span class="s2">&amp;amp;height=</span><span class="p">${</span><span class="nx">height</span><span class="p">}</span><span class="s2">`</span><span class="p">,</span> <span class="na">browser_args</span><span class="p">:</span> <span class="p">{</span> <span class="na">Chrome</span><span class="p">:</span> <span class="p">{</span> <span class="na">ci</span><span class="p">:</span> <span class="p">[</span> <span class="s2">`--window-size=</span><span class="p">${</span><span class="nx">windowSize</span><span class="p">}</span><span class="s2">`</span> <span class="p">]</span> <span class="p">}</span> <span class="p">}</span> <span class="p">};</span> </code></pre> </div> <p>From lines 15-16, we see that <code>DEVICE</code> decides how tests are run. In QUnit, we can use regular expressions to filter tests. I used <strong>lookaheads</strong> to say, "When <code>DEVICE=mobile</code>, only run application tests with <code>@mobile</code> filter or application tests without any filter." I decided to run rendering and unit tests only when <code>DEVICE=desktop</code> because they are likely independent of window size.</p> <p>On line 20, the query parameters <code>width</code> and <code>height</code> are extra and have an important role. I'll explain why they are needed when we write the test helper for Percy.</p> <h3> b. Reset Viewport </h3> <p>Next, we need to apply the <code>.full-screen</code> class to the test container.</p> <p>There are two options. We can create a test helper if there are few application test files (likely for an addon), or an initializer if we have many (likely for an app).<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// Test helper</span> <span class="k">export</span> <span class="k">default</span> <span class="kd">function</span> <span class="nf">resetViewport</span><span class="p">(</span><span class="nx">hooks</span><span class="p">)</span> <span class="p">{</span> <span class="nx">hooks</span><span class="p">.</span><span class="nf">beforeEach</span><span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span> <span class="kd">let</span> <span class="nx">testingContainer</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nf">getElementById</span><span class="p">(</span><span class="dl">'</span><span class="s1">ember-testing-container</span><span class="dl">'</span><span class="p">);</span> <span class="nx">testingContainer</span><span class="p">.</span><span class="nx">classList</span><span class="p">.</span><span class="nf">add</span><span class="p">(</span><span class="dl">'</span><span class="s1">full-screen</span><span class="dl">'</span><span class="p">);</span> <span class="p">});</span> <span class="p">}</span> <span class="c1">// Initializer</span> <span class="k">import</span> <span class="nx">config</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">my-app-name/config/environment</span><span class="dl">'</span><span class="p">;</span> <span class="k">export</span> <span class="kd">function</span> <span class="nf">initialize</span><span class="p">()</span> <span class="p">{</span> <span class="k">if </span><span class="p">(</span><span class="nx">config</span><span class="p">.</span><span class="nx">environment</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">test</span><span class="dl">'</span><span class="p">)</span> <span class="p">{</span> <span class="kd">let</span> <span class="nx">testingContainer</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nf">getElementById</span><span class="p">(</span><span class="dl">'</span><span class="s1">ember-testing-container</span><span class="dl">'</span><span class="p">);</span> <span class="nx">testingContainer</span><span class="p">.</span><span class="nx">classList</span><span class="p">.</span><span class="nf">add</span><span class="p">(</span><span class="dl">'</span><span class="s1">full-screen</span><span class="dl">'</span><span class="p">);</span> <span class="p">}</span> <span class="p">}</span> <span class="k">export</span> <span class="k">default</span> <span class="p">{</span> <span class="nx">initialize</span> <span class="p">}</span> </code></pre> </div> <h3> c. package.json </h3> <p>The last step for an MVP (minimum viable product) is to update the test scripts.</p> <p>Since Ember 3.17, <code>npm-run-all</code> has been available to run scripts in parallel. I'll assume that you also have <code>ember-exam</code> and <code>@percy/ember</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight json"><code><span class="p">{</span><span class="w"> </span><span class="nl">"scripts"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"test"</span><span class="p">:</span><span class="w"> </span><span class="s2">"npm-run-all --parallel test:*"</span><span class="p">,</span><span class="w"> </span><span class="nl">"test:desktop"</span><span class="p">:</span><span class="w"> </span><span class="s2">"percy exec -- ember exam --test-port=7357"</span><span class="p">,</span><span class="w"> </span><span class="nl">"test:mobile"</span><span class="p">:</span><span class="w"> </span><span class="s2">"DEVICE=mobile percy exec -- ember exam --test-port=7358"</span><span class="p">,</span><span class="w"> </span><span class="nl">"test:tablet"</span><span class="p">:</span><span class="w"> </span><span class="s2">"DEVICE=tablet percy exec -- ember exam --test-port=7359"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre> </div> <p>In addition to setting <code>DEVICE</code>, it's crucial to use different port numbers. Now, we can run <code>yarn test</code> to check our app at 3 window sizes. If you have disparate amounts of tests for desktop, mobile, and tablet, you can set different <code>--split</code> values so that you allocate more partitions to one window size. For example, 4 partitions to desktop, 2 to mobile, and 1 to tablet.</p> <h3> d. CI </h3> <p>Your code change may depend on what features your CI provider offers and how many <code>ember-exam</code> partitions you used to test a window size. I don't know what your CI looks like right now, so I'll make a handwave.</p> <p>In <code>ember-container-query</code>, I didn't split tests into multiple partitions. There simply weren't that many. As a result, I was able to use <code>matrix</code> to simplify the workflow:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="na">jobs</span><span class="pi">:</span> <span class="na">test-addon</span><span class="pi">:</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">device</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">desktop</span><span class="pi">,</span> <span class="nv">mobile</span><span class="pi">,</span> <span class="nv">tablet</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">percy/exec-action@v0.3.0</span> <span class="na">run</span><span class="pi">:</span> <span class="na">custom-command</span><span class="pi">:</span> <span class="s">yarn test:${{ matrix.device }}</span> </code></pre> </div> <h3> e. Test Helper for Percy </h3> <p>The end is the beginning is the end. We want to write a test helper for Percy, the thing that launched me into a journey of discovery.</p> <p>In its simplest form, the test helper understands filters and knows the window size. It also generates a unique snapshot name that is human readable.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="k">import</span> <span class="nx">percySnapshot</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">@percy/ember</span><span class="dl">'</span><span class="p">;</span> <span class="k">export</span> <span class="k">default</span> <span class="k">async</span> <span class="kd">function</span> <span class="nf">takeSnapshot</span><span class="p">(</span><span class="nx">qunitAssert</span><span class="p">)</span> <span class="p">{</span> <span class="kd">const</span> <span class="nx">name</span> <span class="o">=</span> <span class="nf">getName</span><span class="p">(</span><span class="nx">qunitAssert</span><span class="p">);</span> <span class="kd">const</span> <span class="p">{</span> <span class="nx">height</span><span class="p">,</span> <span class="nx">width</span> <span class="p">}</span> <span class="o">=</span> <span class="nf">getWindowSize</span><span class="p">();</span> <span class="k">await</span> <span class="nf">percySnapshot</span><span class="p">(</span><span class="nx">name</span><span class="p">,</span> <span class="p">{</span> <span class="na">widths</span><span class="p">:</span> <span class="p">[</span><span class="nx">width</span><span class="p">],</span> <span class="na">minHeight</span><span class="p">:</span> <span class="nx">height</span> <span class="p">});</span> <span class="p">}</span> <span class="kd">function</span> <span class="nf">getName</span><span class="p">(</span><span class="nx">qunitAssert</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span> <span class="kd">function</span> <span class="nf">getWindowSize</span><span class="p">()</span> <span class="p">{</span> <span class="kd">const</span> <span class="nx">queryParams</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">URLSearchParams</span><span class="p">(</span><span class="nb">window</span><span class="p">.</span><span class="nx">location</span><span class="p">.</span><span class="nx">search</span><span class="p">);</span> <span class="k">return</span> <span class="p">{</span> <span class="na">height</span><span class="p">:</span> <span class="nc">Number</span><span class="p">(</span><span class="nx">queryParams</span><span class="p">.</span><span class="nf">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">height</span><span class="dl">'</span><span class="p">)),</span> <span class="na">width</span><span class="p">:</span> <span class="nc">Number</span><span class="p">(</span><span class="nx">queryParams</span><span class="p">.</span><span class="nf">get</span><span class="p">(</span><span class="dl">'</span><span class="s1">width</span><span class="dl">'</span><span class="p">))</span> <span class="p">};</span> <span class="p">}</span> </code></pre> </div> <p>On line 13, I hid implementation details. The idea is to transform QUnit's <code>assert</code> object into a string.</p> <p>Line 16 is the interesting bit. Earlier, when we updated <code>testem.js</code>, I mentioned passing width and height as query parameters. I tried two other approaches before.</p> <p>In my first attempt, I stored <code>process.env.DEVICE</code> in <code>config/environment.js</code> and imported the file to the test helper file. From <code>WINDOW_SIZES</code>, one can find out width and height from <code>DEVICE</code>. For QUnit, this worked. For Percy, it did not. Since <code>v2.x</code>, Percy doesn't hook into the Ember build pipeline so <code>DEVICE</code> was <code>undefined</code>.</p> <p>In my second attempt, I used <code>window.innerWidth</code> and <code>window.innerHeight</code> to get direct measurements. <code>innerWidth</code> gave the correct width, but <code>innerHeight</code> turned out to be unreliable. Because I wanted to test at multiple widths and multiple heights, I rejected this approach as well.</p> <h2> 3. How to Run Tests </h2> <p>After we make these changes, an important question remains. How do we run tests locally?</p> <ul> <li> <code>yarn test</code> to run all desktop, mobile, and tablet tests in parallel</li> <li> <code>yarn test:desktop --server</code> to run all desktop tests with <code>--server</code> option</li> <li> <code>DEVICE=mobile ember test --filter='@mobile A user can do X in Dashboard'</code> to run a particular test</li> </ul> <h2> 4. What's Next? </h2> <p>On the long horizon, I'd like us to reexamine and change why we are currently limited to testing 1 resolution. Ember's testing story is an already amazing one. I believe the ability to test multiple resolutions (and do so easily without taking 5 steps like above) would make that story even better.</p> <p>For nearer goals, I'd like us to iron out a couple of issues in overriding <code>ember-qunit</code>:</p> <ul> <li>Even with <code>.full-screen</code>, the test container's height can be off if we use <code>--server</code> to launch the test browser. If assertions sometimes fail due to incorrect window size, it's harder to separate true and false positives.</li> <li>Visiting <code>localhost:4200/tests</code> to start tests will also throw off the test container's width and height. It may be impractical to ask developers to run tests with <code>--server</code> because this does not launch Ember Inspector.</li> </ul> <p>We need to look at allowing cross-resolution testing for <code>ember-mocha</code> as well.</p> <h2> 5. Notes </h2> <p>Special thanks to my team Sean Massa, Trek Glowacki, and Saf Suleman for trying out a dangerously unproven, new testing approach with me.</p> ember javascript testing showdev Isaac Lee Thu, 04 Jun 2020 12:20:36 +0000 https://dev.to/ijlee2/container-queries-adaptive-images-264l https://dev.to/ijlee2/container-queries-adaptive-images-264l <p><em>Originally published on <a href="http://crunchingnumbers.live/">crunchingnumbers.live</a></em></p> <p>A powerful application of container queries is <strong>adaptive images</strong>. It's about striking the balance between displaying an image that looks good (the larger the better) and one that loads fast (the smaller the better).</p> <p>Currently, we are limited to <a href="https://developer.mozilla.org/docs/Web/API/HTMLImageElement/srcset"><code>srcset</code></a>, which selects the optimal image based on the global screen size. This may work for splash images that cover the whole width, but what about images that we show in a partial area?</p> <p>Enter <a href="https://github.com/ijlee2/ember-container-query">container query</a>. We can compare every candidate image's width, height, and aspect ratio (I assume that we have these information via metadata) to those of the container, then use the best fitting image's URL.</p> <p>In practice, we <strong>create a component</strong> and pass an array of images. (Here, by an image, I mean a POJO with just URL and metadata, not the actual image.)<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight html"><code><span class="nt">&lt;ContainerQuery</span> <span class="na">as</span> <span class="err">|</span><span class="na">CQ</span><span class="err">|</span><span class="nt">&gt;</span> <span class="nt">&lt;div</span> <span class="na">local-class=</span><span class="s">"image-container"</span> <span class="err">{{</span><span class="na">did-update</span> <span class="err">(</span><span class="na">fn</span> <span class="na">this.setImageSource</span> <span class="na">CQ.dimensions</span><span class="err">)</span> <span class="na">CQ.dimensions</span> <span class="err">}}</span> <span class="nt">&gt;</span> <span class="nt">&lt;img</span> <span class="na">local-class=</span><span class="s">"image"</span> <span class="na">src=</span><span class="s">{{this.src}}</span> <span class="nt">/&gt;</span> <span class="nt">&lt;/div&gt;</span> <span class="nt">&lt;/ContainerQuery&gt;</span> </code></pre> </div> <p>In the backing class, <code>setImageSource</code> calls <code>findBestFittingImage</code> to set <code>this.src</code>. The latter function exists in a utility so that we can write fast unit tests.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="k">export</span> <span class="kd">function</span> <span class="nx">findBestFittingImage</span><span class="p">(</span><span class="nx">images</span><span class="p">,</span> <span class="nx">containerDimensions</span><span class="p">)</span> <span class="p">{</span> <span class="kd">const</span> <span class="p">{</span> <span class="nx">aspectRatio</span><span class="p">,</span> <span class="nx">height</span><span class="p">,</span> <span class="nx">width</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">containerDimensions</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">imagesRanked</span> <span class="o">=</span> <span class="nx">images</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">image</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="kd">const</span> <span class="p">{</span> <span class="nx">url</span><span class="p">,</span> <span class="nx">metadata</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">image</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">imageHeight</span> <span class="o">=</span> <span class="nx">metadata</span><span class="p">.</span><span class="nx">height</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">imageWidth</span> <span class="o">=</span> <span class="nx">metadata</span><span class="p">.</span><span class="nx">width</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">imageAspectRatio</span> <span class="o">=</span> <span class="nx">imageWidth</span> <span class="o">/</span> <span class="nx">imageHeight</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">arMetric</span> <span class="o">=</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">abs</span><span class="p">(</span><span class="nx">imageAspectRatio</span> <span class="o">-</span> <span class="nx">aspectRatio</span><span class="p">);</span> <span class="kd">const</span> <span class="nx">hwMetric</span> <span class="o">=</span> <span class="p">((</span><span class="nx">imageHeight</span> <span class="o">-</span> <span class="nx">height</span><span class="p">)</span> <span class="o">**</span> <span class="mi">3</span> <span class="o">+</span> <span class="p">(</span><span class="nx">imageWidth</span> <span class="o">-</span> <span class="nx">width</span><span class="p">)</span> <span class="o">**</span> <span class="mi">3</span><span class="p">)</span> <span class="o">**</span> <span class="p">(</span><span class="mi">1</span><span class="o">/</span><span class="mi">3</span><span class="p">);</span> <span class="kd">const</span> <span class="nx">hwTiebreaker</span> <span class="o">=</span> <span class="p">((</span><span class="nx">imageHeight</span> <span class="o">-</span> <span class="nx">height</span><span class="p">)</span> <span class="o">**</span> <span class="mi">2</span> <span class="o">+</span> <span class="p">(</span><span class="nx">imageWidth</span> <span class="o">-</span> <span class="nx">width</span><span class="p">)</span> <span class="o">**</span> <span class="mi">2</span><span class="p">)</span> <span class="o">**</span> <span class="p">(</span><span class="mi">1</span><span class="o">/</span><span class="mi">2</span><span class="p">);</span> <span class="k">return</span> <span class="p">{</span> <span class="nx">url</span><span class="p">,</span> <span class="nx">arMetric</span><span class="p">,</span> <span class="na">hwMetric</span><span class="p">:</span> <span class="nb">Number</span><span class="p">.</span><span class="nb">isNaN</span><span class="p">(</span><span class="nx">hwMetric</span><span class="p">)</span> <span class="p">?</span> <span class="kc">Infinity</span> <span class="p">:</span> <span class="nx">hwMetric</span><span class="p">,</span> <span class="nx">hwTiebreaker</span> <span class="p">};</span> <span class="p">})</span> <span class="p">.</span><span class="nx">sort</span><span class="p">((</span><span class="nx">a</span><span class="p">,</span> <span class="nx">b</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="nx">a</span><span class="p">.</span><span class="nx">arMetric</span> <span class="o">&gt;</span> <span class="nx">b</span><span class="p">.</span><span class="nx">arMetric</span><span class="p">)</span> <span class="k">return</span> <span class="mi">1</span><span class="p">;</span> <span class="k">if</span> <span class="p">(</span><span class="nx">a</span><span class="p">.</span><span class="nx">arMetric</span> <span class="o">&lt;</span> <span class="nx">b</span><span class="p">.</span><span class="nx">arMetric</span><span class="p">)</span> <span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span> <span class="k">if</span> <span class="p">(</span><span class="nx">a</span><span class="p">.</span><span class="nx">hwMetric</span> <span class="o">&gt;</span> <span class="nx">b</span><span class="p">.</span><span class="nx">hwMetric</span><span class="p">)</span> <span class="k">return</span> <span class="mi">1</span><span class="p">;</span> <span class="k">if</span> <span class="p">(</span><span class="nx">a</span><span class="p">.</span><span class="nx">hwMetric</span> <span class="o">&lt;</span> <span class="nx">b</span><span class="p">.</span><span class="nx">hwMetric</span><span class="p">)</span> <span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span> <span class="k">return</span> <span class="nx">a</span><span class="p">.</span><span class="nx">hwTiebreaker</span> <span class="o">-</span> <span class="nx">b</span><span class="p">.</span><span class="nx">hwTiebreaker</span><span class="p">;</span> <span class="p">});</span> <span class="k">return</span> <span class="nx">imagesRanked</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="nx">url</span><span class="p">;</span> <span class="p">}</span> </code></pre> </div> <p>The formulas for <code>arMetric</code>, <code>hwMetric</code>, and <code>hwTiebreaker</code> aren't anything special. I'm using <em>l^p</em> norms to quantify the difference between an image and the container. I can put them into words by saying I'm making 3 assumptions:</p> <ol> <li>Users prefer images whose aspect ratio is close to the container's.</li> <li>Users prefer images whose height and width are larger than the container's.</li> <li>If all images are smaller than the container, users want the image that comes closest to the container.</li> </ol> <p>That's it! With a bit of JavaScript and math, we solved a problem that MDN says is not possible (I paraphrased):</p> <blockquote> <p>[H]ence the need to implement solutions like <code>srcset</code>. For example, you couldn't load the <code>&lt;img&gt;</code> element, then detect the viewport width with JavaScript, and then dynamically change the source image to a smaller one if desired. By then, the original image would already have been loaded, and you would load the small image as well, which is even worse in responsive image terms.</p> <p><a href="https://developer.mozilla.org/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images">Why can't we just do this using CSS or JavaScript? - MDN</a></p> </blockquote> <p>Here are my <a href="https://github.com/ijlee2/ember-container-query/tree/master/tests/dummy/app/components/widgets/widget-3/tour-schedule/responsive-image">code for adaptive images</a> and <a href="https://github.com/ijlee2/ember-container-query/blob/master/tests/unit/utils/widgets/widget-3-test.js">tests</a>. There's more to do so I encourage you to extend my work. I made an ideal assumption about where I'm getting image URLs and metadata. Do things change when they come from a network request? Are there better ranking algorithms? I look forward to see what you can do with <a href="https://github.com/ijlee2/ember-container-query">container queries</a>.</p> ember javascript webdev css Isaac Lee Tue, 02 Jun 2020 03:27:27 +0000 https://dev.to/ijlee2/container-queries-reimagined-2a6d https://dev.to/ijlee2/container-queries-reimagined-2a6d <p><em>Originally published on <a href="https://crunchingnumbers.live/2020/06/01/container-queries-reimagined/" rel="noopener noreferrer">crunchingnumbers.live</a></em></p> <p>On Friday, I published my first addon. It's called <a href="https://github.com/ijlee2/ember-container-query/" rel="noopener noreferrer">ember-container-query</a>. Becoming an addon author was one of my goals for 2020, so I'm especially proud of it and hope that you will find a good use.</p> <p>Container queries aren't new in Ember. My addon is based on Chad Carbert's <a href="https://github.com/chadian/ember-fill-up" rel="noopener noreferrer">ember-fill-up</a> from 2019. That, in turn, credits Andrey Mikhaylov's <a href="https://github.com/lolmaus/ember-element-query" rel="noopener noreferrer">ember-element-query</a> from 2017. I even found a <a href="https://gregbabiars.com/responsive-ember-components/" rel="noopener noreferrer">blog post</a> from 2015, by Greg Babiars!</p> <p>Simplicity is what makes <code>ember-container-query</code> different from the previous tries. I combined 2 atomic solutions (<strong>modifiers</strong>, introduced in Ember Octane) to arrive at <em>the</em> atomic solution to container queries.</p> <p>Because I practiced code composition and provided the minimum necessary API, the benefits are twofold. I have fewer code to maintain, while you have a choice to build your code on top of my addon or another with a similar API.</p> <p>Testing is the second differentiator. With every code change, the <a href="https://crunchingnumbers.live/2020/03/17/ci-with-github-actions-for-ember-apps/" rel="noopener noreferrer">CI</a> checks that my addon and demo app work <strong>no matter the window size</strong>. Testing multiple windows is <em>kinda</em> important for container queries.</p> <p>To my knowledge, no Ember app or addon has tried testing multiple windows and publicly released their solution. In the next article, I will go over how you can update the default test setup to achieve this feat.</p> <p>In the meantime, I encourage you to learn <a href="https://github.com/ijlee2/ember-container-query#applications" rel="noopener noreferrer">what container queries can do for you</a> and get inspiration from my <a href="https://ember-container-query.netlify.app/" rel="noopener noreferrer">demo app</a>. The code is publicly available on <a href="https://github.com/ijlee2/ember-container-query/tree/master/tests/dummy/app" rel="noopener noreferrer">GitHub</a>.</p> <p><a href="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fuser-images.githubusercontent.com%2F16869656%2F82177207-72699c00-989e-11ea-9cb6-2e388c5e98c0.gif" class="article-body-image-wrapper"><img src="https://media.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fuser-images.githubusercontent.com%2F16869656%2F82177207-72699c00-989e-11ea-9cb6-2e388c5e98c0.gif" alt="Demo of ember-container-query"></a></p> ember showdev javascript webdev Isaac Lee Tue, 17 Mar 2020 17:35:08 +0000 https://dev.to/ijlee2/ci-with-github-actions-for-ember-apps-oim https://dev.to/ijlee2/ci-with-github-actions-for-ember-apps-oim <p><em>Originally published on <a href="https://crunchingnumbers.live/2020/03/17/ci-with-github-actions-for-ember-apps/">crunchingnumbers.live</a></em></p> <p>Lately I've been working on <a href="https://ember-music.herokuapp.com/">Ember Music</a>, an app that I can use as a playground to test addons and ideas in Ember. When I need to write a blog post, I can reach for this app instead of designing a new one each time. Since the app will grow over time, I wanted to introduce <strong>continuous integration</strong> (CI) and <strong>continuous deployment</strong> early.</p> <p><a href="https://dashboard.heroku.com/">Heroku Dashboard</a> makes deploying code on GitHub simple. From the Deploy tab, you select GitHub, find your repo, then check "Wait for CI to pass before deploy."</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--pQbXxSUr--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/introduction_heroku.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--pQbXxSUr--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/introduction_heroku.png" alt="" width="800" height="427"></a></p> Heroku makes deploying code on GitHub simple. <p>For continuous integration, I tried out <a href="https://github.com/features/actions">GitHub Actions</a> since it is free (there are limits to minutes and storage for private repos) and my code is on GitHub. I also wanted to find an alternative to Codeship Pro that I use for work. One app has about 150 tests, but CI time wildly varies between 3 and 15 minutes. Because ten minutes is how long CI took for a larger app that I had worked on, I haven't been content.</p> <p>With GitHub Actions, I was able to make a <strong>workflow</strong> that did everything I want:</p> <ul> <li>Set operating system and Node version</li> <li>Cache ​dependencies (avoid <code>yarn install</code>)</li> <li>Lint files and dependencies</li> <li>Run tests separately from linting</li> <li>Split tests and run in parallel</li> <li>Take <a href="https://docs.percy.io/docs/ember">Percy</a> snapshots in parallel</li> <li>Be cost effective</li> </ul> <p>In this blog post, I will share my workflow because there is a high chance that you, too, want to solve the problems listed above. Rather than dumping the entire workflow on you, I will start with a simple one and let it organically grow. Throughout, I will assume that you use <code>yarn</code> to manage packages. If you use <code>npm</code>, please check the GitHub Gist at the end to see the differences.</p> <h1> 1. I Want to Run Tests </h1> <p>Testing is available to every Ember app and is integral to CI, so let's look at how to write a workflow that runs <code>ember test</code>. Along the way, you will see how to set the operating system and Node version.</p> <h2> a. Create Workflow </h2> <p>In the root of your project, create folders called <code>.github</code> and <code>.github/workflows</code>. All workflows must be stored in <code>.github/workflows</code>. Workflows are written in YAML, so let's create a file called <code>ci.yml</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code><span class="c"># Folder structure</span> ember-music │ ├── .github │ │ │ └── workflows │ │ │ └── ci.yml │ ├── app │ │ ... │ ├── tests │ │ ... │ ├── package.json │ └── yarn.lock </code></pre> </div> <p>In the file, we can use the <code>on</code> and <code>jobs</code> keys to specify when CI runs and what it does. We can also give the workflow a <code>name</code>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="c1"># File: .github/workflows/ci.yml</span> <span class="na">name</span><span class="pi">:</span> <span class="s">CI</span> <span class="na">on</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">push</span><span class="pi">,</span> <span class="nv">pull_request</span><span class="pi">]</span> <span class="na">jobs</span><span class="pi">:</span> </code></pre> </div> <p>If you commit and push this file, the workflow will fail in an instant. (GitHub does notify you by email.) On GitHub, let's click on the Actions tab, then find the workflow to see what went wrong. The error message shows that we haven't defined jobs.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--RFgA7lsH--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_1a_github_actions.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--RFgA7lsH--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_1a_github_actions.png" alt="" width="800" height="667"></a></p> GitHub Actions alerts us we haven't defined jobs. <h2> b. Define Jobs </h2> <p>A workflow must have one or more jobs to do. A <strong>job</strong> is completed by following a set of <code>steps</code>. At each <strong>step</strong>, we can <code>run</code> a command or <code>use</code> an action (custom or imported) to do something meaningful—something that gets us closer to finishing the job.</p> <p>When someone makes a push or pull request, a CI's job is to run tests. Think about what steps you take to test someone else's Ember app. Likely, you would:</p> <ol> <li>Clone the repo.</li> <li>Set the Node version, maybe with <code>nvm</code>.</li> <li>Run <code>yarn</code> to install dependencies.</li> <li>Run <code>ember test</code>.</li> </ol> <p>Guess what? We can tell a workflow to do the same!<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="c1"># File: .github/workflows/ci.yml</span> <span class="na">name</span><span class="pi">:</span> <span class="s">CI</span> <span class="na">on</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">push</span><span class="pi">,</span> <span class="nv">pull_request</span><span class="pi">]</span> <span class="na">jobs</span><span class="pi">:</span> <span class="na">test</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Run tests</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/checkout@v2</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Use Node.js ${{ matrix.node-version }}</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/setup-node@v1</span> <span class="na">with</span><span class="pi">:</span> <span class="na">node-version</span><span class="pi">:</span> <span class="s">${{ matrix.node-version }}</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Install dependencies</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn install --frozen-lockfile</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test Ember app</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn test</span> </code></pre> </div> <p>Because checking out a repo and setting up Node are common tasks, GitHub Actions provides actions that you can just call. The <code>matrix</code> key lets you run the workflow on various operating systems and Node versions. Since I'm writing the app for myself, I specified one OS and Node version. If you are developing an addon for other people, you will likely specify more (take <a href="https://github.com/ember-cli/ember-try">Ember versions</a> into account, too).</p> <p>You may have noticed that I ran <code>yarn test</code>. I did so because <code>package.json</code> provides a script called <code>test</code>. In Ember 3.16, these are the default scripts:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// File: package.json</span> <span class="p">{</span> <span class="p">...</span> <span class="dl">"</span><span class="s2">scripts</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="dl">"</span><span class="s2">build</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember build --environment=production</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:hbs</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember-template-lint .</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:js</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">eslint .</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">start</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember serve</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">test</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember test</span><span class="dl">"</span> <span class="p">}</span> <span class="p">...</span> <span class="p">}</span> </code></pre> </div> <p>In short, running <code>yarn test</code> means running <code>ember test</code>. By relying on the scripts in <code>package.json</code>, CI can check our code in the same manner as we might locally. We'll update these scripts as we expand the workflow.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--Ra7anKrV--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_1b_github_actions.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--Ra7anKrV--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_1b_github_actions.png" alt="" width="800" height="427"></a></p> GitHub Actions can run Ember tests. <h2> c. When Should CI Run? </h2> <p>In the sections above and below, I used <code>on: [push, pull_request]</code> for simplicity.</p> <p>For a production app where you would create branches, make pull requests (PRs), then merge to <code>master</code> branch, consider instead:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="c1"># File: .github/workflows/ci.yml</span> <span class="na">name</span><span class="pi">:</span> <span class="s">CI</span> <span class="na">on</span><span class="pi">:</span> <span class="na">push</span><span class="pi">:</span> <span class="na">branches</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">master</span> <span class="na">pull_request</span><span class="pi">:</span> <span class="nn">...</span> </code></pre> </div> <p>Then, your CI will run according to these rules:</p> <ul> <li>If you create a branch and make a push, CI will not run.</li> <li>If you create a PR for that branch (draft or open), CI will run. GitHub Actions shows the run type to be <code>pull_request</code>.</li> <li>Marking a draft PR as ready (open) will not trigger CI again. 👍</li> <li>Any additional pushes that you make to the PR will trigger CI. (type: <code>pull_request</code>)</li> <li>If you merge the PR into <code>master</code>, CI will run once more. (type: <code>push</code>)</li> </ul> <h1> 2. I Want to Lint </h1> <p>A CI can also lint files and dependencies. Before the app becomes large and unwieldy, we want to ensure that our code follows a standard and relies on a single version for each package.</p> <p>Rather than adding a step to our existing job, we can create 2 jobs—one for linting and another for running tests—so that they can run in parallel. In GitHub Actions, we specify an extra job like this:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="c1"># File: .github/workflows/ci.yml</span> <span class="na">name</span><span class="pi">:</span> <span class="s">CI</span> <span class="na">on</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">push</span><span class="pi">,</span> <span class="nv">pull_request</span><span class="pi">]</span> <span class="na">jobs</span><span class="pi">:</span> <span class="na">lint</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Lint files and dependencies</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/checkout@v2</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Use Node.js ${{ matrix.node-version }}</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/setup-node@v1</span> <span class="na">with</span><span class="pi">:</span> <span class="na">node-version</span><span class="pi">:</span> <span class="s">${{ matrix.node-version }}</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Install dependencies</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn install --frozen-lockfile</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">lint:dependency</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn lint:dependency</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">lint:hbs</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn lint:hbs</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">lint:js</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn lint:js</span> <span class="na">test</span><span class="pi">:</span> <span class="s">...</span> </code></pre> </div> <p>Although duplicate code (lines 14-23) are an eyesore, we'll repeat steps for simplicity—take baby steps to understanding GitHub Actions. At this point, we are more concerned by if the workflow will still pass than if GitHub Actions allows a "beforeEach hook." (The feature that'd let us DRY steps is called <strong>YAML anchor</strong>. At the time of writing, <a href="https://github.community/t5/GitHub-Actions/Support-for-YAML-anchors/m-p/30336">anchors are not supported</a>.)</p> <p>From line 26, you might guess that <code>package.json</code> has an additional script. Indeed, it runs the addon <a href="https://github.com/salsify/ember-cli-dependency-lint">ember-cli-dependency-lint</a>.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// File: package.json</span> <span class="p">{</span> <span class="p">...</span> <span class="dl">"</span><span class="s2">scripts</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="dl">"</span><span class="s2">build</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember build --environment=production</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:dependency</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember dependency-lint</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:hbs</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember-template-lint .</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:js</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">eslint .</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">start</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember serve</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">test</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember test --query=nolint</span><span class="dl">"</span> <span class="p">}</span> <span class="p">...</span> <span class="p">}</span> </code></pre> </div> <p>By default, Ember QUnit lints if you have <code>ember-cli-eslint</code>, <code>ember-cli-template-lint</code>, or <code>ember-cli-dependency-lint</code>. Now that we have a job dedicated to linting, I passed <code>--query=nolint</code> so that the job for testing does not lint again.</p> <p>As an aside, starting with <a href="https://blog.emberjs.com/2020/03/16/ember-3-17-released.html">Ember 3.17</a>, you are advised to remove <code>ember-cli-eslint</code> and <code>ember-cli-template-lint</code> in favor of using <code>eslint</code> and <code>ember-template-lint</code>. The one exception is if you need <em>live</em> linting. But chances are, you don't thanks to CI. You can now enjoy faster build and rebuild!</p> <p>Let's commit changes and push. When you see 2 green checks, let out that sigh.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--j5NhTenG--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_2_github_actions-1.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--j5NhTenG--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_2_github_actions-1.png" alt="" width="800" height="427"></a></p> GitHub Actions can lint and run tests at the same time. <h1> 3. I Want to Run Tests in Parallel </h1> <p>We can <a href="https://crunchingnumbers.live/2019/10/11/write-tests-like-a-mathematician-part-3/">promote writing more tests</a> if the time to run them can remain small. One way to achieve this is to split tests and run them in parallel using <a href="https://ember-cli.com/ember-exam/">Ember Exam</a>.</p> <h2> a. Setup </h2> <p>After you install <code>ember-exam</code>, please open the file <code>tests/test-helper.js</code>. You must replace the <code>start</code> method from Ember QUnit (or Mocha) with the one from Ember Exam. Otherwise, running the command <code>ember exam</code> has no effect.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// File: tests/test-helper.js</span> <span class="k">import</span> <span class="nx">Application</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">../app</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="nx">config</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">../config/environment</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="p">{</span> <span class="nx">setApplication</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">@ember/test-helpers</span><span class="dl">'</span><span class="p">;</span> <span class="k">import</span> <span class="nx">start</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ember-exam/test-support/start</span><span class="dl">'</span><span class="p">;</span> <span class="nx">setApplication</span><span class="p">(</span><span class="nx">Application</span><span class="p">.</span><span class="nx">create</span><span class="p">(</span><span class="nx">config</span><span class="p">.</span><span class="nx">APP</span><span class="p">));</span> <span class="nx">start</span><span class="p">({</span> <span class="na">setupTestIsolationValidation</span><span class="p">:</span> <span class="kc">true</span> <span class="p">});</span> </code></pre> </div> <h2> b. Divide and Conquer </h2> <p>By trial and error, I came up with a script that I hope works for you too:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// File: package.json</span> <span class="p">{</span> <span class="p">...</span> <span class="dl">"</span><span class="s2">scripts</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="dl">"</span><span class="s2">build</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember build --environment=production</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:dependency</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember dependency-lint</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:hbs</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember-template-lint .</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:js</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">eslint .</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">start</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember serve</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">test</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember exam --query=nolint --split=4 --parallel=1</span><span class="dl">"</span> <span class="p">}</span> <span class="p">...</span> <span class="p">}</span> </code></pre> </div> <p>I wrote the script so that we can append flags to do useful things. With <code>yarn test --server</code>, for example, you should see 4 browsers running. Good to have a sanity check. Each browser—a <strong>partition</strong>—handles roughly a quarter of the tests. If you use QUnit, you can run <code>yarn test --server --random</code> to check if your tests are order-dependent.</p> <p>Most importantly, the script allows us to append the <code>--partition</code> flag so that GitHub Actions knows how to run Ember tests in parallel. Let's rename the job called <code>test</code> to <code>test-partition-1</code> and update its last step to run partition 1. Then, create three more jobs to run partitions 2 to 4.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="c1"># File: .github/workflows/ci.yml</span> <span class="na">name</span><span class="pi">:</span> <span class="s">CI</span> <span class="na">on</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">push</span><span class="pi">,</span> <span class="nv">pull_request</span><span class="pi">]</span> <span class="na">jobs</span><span class="pi">:</span> <span class="na">lint</span><span class="pi">:</span> <span class="s">...</span> <span class="na">test-partition-1</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Run tests - Partition </span><span class="m">1</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/checkout@v2</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Use Node.js ${{ matrix.node-version }}</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/setup-node@v1</span> <span class="na">with</span><span class="pi">:</span> <span class="na">node-version</span><span class="pi">:</span> <span class="s">${{ matrix.node-version }}</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Install dependencies</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn install --frozen-lockfile</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test Ember app</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn test --partition=1</span> <span class="na">test-partition-2</span><span class="pi">:</span> <span class="s">...</span> <span class="na">test-partition-3</span><span class="pi">:</span> <span class="s">...</span> <span class="na">test-partition-4</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Run tests - Partition </span><span class="m">4</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/checkout@v2</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Use Node.js ${{ matrix.node-version }}</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/setup-node@v1</span> <span class="na">with</span><span class="pi">:</span> <span class="na">node-version</span><span class="pi">:</span> <span class="s">${{ matrix.node-version }}</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Install dependencies</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn install --frozen-lockfile</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test Ember app</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn test --partition=4</span> </code></pre> </div> <p>Now, the workflow has 5 jobs. You can check that tests do run separately from linting and in parallel. You can also check that each partition has a different set of tests.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--g3onO5J---/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_3b_github_actions.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--g3onO5J---/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_3b_github_actions.png" alt="" width="800" height="667"></a></p> GitHub Actions can run tests in parallel. <p>Unfortunately, everything isn't awesome. Each job has to run <code>yarn install</code>, and this will happen every time we make a push or pull request. When you think about it, linting and running tests can rely on the same setup so why install 5 times? Furthermore, if packages didn't change since the last build, we could skip installation altogether.</p> <p>Let's take a look at how to <strong>cache</strong> in GitHub Actions next.</p> <h1> 4. I Want to Cache </h1> <p>Here is where things began to fall apart for me. The documentation didn't make it clear that the way to cache <em>differs</em> between <code>yarn</code> and <code>npm</code>. It also didn't show how to avoid <code>yarn install</code> when the cache <em>is</em> available and up-to-date. Hopefully, this section will save you from agony.</p> <p>To illustrate caching, I'll direct your attention to one job, say <code>test-partition-1</code>:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="c1"># File: .github/workflows/ci.yml</span> <span class="na">name</span><span class="pi">:</span> <span class="s">CI</span> <span class="na">on</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">push</span><span class="pi">,</span> <span class="nv">pull_request</span><span class="pi">]</span> <span class="na">jobs</span><span class="pi">:</span> <span class="na">test-partition-1</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Run tests - Partition </span><span class="m">1</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/checkout@v2</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Use Node.js ${{ matrix.node-version }}</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/setup-node@v1</span> <span class="na">with</span><span class="pi">:</span> <span class="na">node-version</span><span class="pi">:</span> <span class="s">${{ matrix.node-version }}</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Install dependencies</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn install --frozen-lockfile</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test Ember app</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn test --partition=1</span> </code></pre> </div> <p>We want to know how to update lines 22-23 so that the job does <code>yarn install</code> only when necessary. The changes that we will make also apply to the other jobs.</p> <p>The idea is simple. First, <code>yarn</code> keeps a <strong>global cache</strong> that stores every package that you use. This way, it doesn't need to download the same package again. We want to cache that global cache. Second, from experience, we know that creating the <code>node_modules</code> folder takes time. Let's cache that too! When the global cache or <code>node_modules</code> folder is out of date, we will run <code>yarn install</code>.</p> <p>The hard parts are digging documentation and scouring the web for examples. I'll save you the trouble. In the end, we get lines 22-48:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="c1"># File: .github/workflows/ci.yml</span> <span class="na">name</span><span class="pi">:</span> <span class="s">CI</span> <span class="na">on</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">push</span><span class="pi">,</span> <span class="nv">pull_request</span><span class="pi">]</span> <span class="na">jobs</span><span class="pi">:</span> <span class="na">test-partition-1</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Run tests - Partition </span><span class="m">1</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/checkout@v2</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Use Node.js ${{ matrix.node-version }}</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/setup-node@v1</span> <span class="na">with</span><span class="pi">:</span> <span class="na">node-version</span><span class="pi">:</span> <span class="s">${{ matrix.node-version }}</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Get Yarn cache path</span> <span class="na">id</span><span class="pi">:</span> <span class="s">yarn-cache-dir-path</span> <span class="na">run</span><span class="pi">:</span> <span class="s">echo "::set-output name=dir::$(yarn cache dir)"</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Cache Yarn cache</span> <span class="na">id</span><span class="pi">:</span> <span class="s">cache-yarn-cache</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/cache@v1</span> <span class="na">with</span><span class="pi">:</span> <span class="na">path</span><span class="pi">:</span> <span class="s">${{ steps.yarn-cache-dir-path.outputs.dir }}</span> <span class="na">key</span><span class="pi">:</span> <span class="s">${{ runner.os }}-${{ matrix.node-version }}-yarn-${{ hashFiles('**/yarn.lock') }}</span> <span class="na">restore-keys</span><span class="pi">:</span> <span class="pi">|</span> <span class="s">${{ runner.os }}-${{ matrix.node-version }}-yarn-</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Cache node_modules</span> <span class="na">id</span><span class="pi">:</span> <span class="s">cache-node-modules</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">actions/cache@v1</span> <span class="na">with</span><span class="pi">:</span> <span class="na">path</span><span class="pi">:</span> <span class="s">node_modules</span> <span class="na">key</span><span class="pi">:</span> <span class="s">${{ runner.os }}-${{ matrix.node-version }}-nodemodules-${{ hashFiles('**/yarn.lock') }}</span> <span class="na">restore-keys</span><span class="pi">:</span> <span class="pi">|</span> <span class="s">${{ runner.os }}-${{ matrix.node-version }}-nodemodules-</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Install dependencies</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn install --frozen-lockfile</span> <span class="na">if</span><span class="pi">:</span> <span class="pi">|</span> <span class="s">steps.cache-yarn-cache.outputs.cache-hit != 'true' ||</span> <span class="s">steps.cache-node-modules.outputs.cache-hit != 'true'</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test Ember app</span> <span class="na">run</span><span class="pi">:</span> <span class="s">yarn test --partition=1</span> </code></pre> </div> <p>Amid the changes, I want you to grasp just 3 things.</p> <p>First, the workflow needs to know where to find the global cache to cache it. We use <code>yarn cache dir</code> to find the path (line 24) and pass it to the next step via <code>id</code> (line 23) so that we don't hardcode a path that works for one OS but not others. (For <code>npm</code>, the documentation showed <code>path: ~/.npm</code>. It works in Linux and Mac, but not Windows.)</p> <p>Second, the workflow needs to know when it is okay to use a cache. The criterion will depend on what we're caching. For the global cache and <code>node_modules</code> folder, we can be certain that it's okay to use the cache if <code>yarn.lock</code> hasn't changed. <code>hashFiles()</code> allows us to check for a file difference with efficiency and high confidence. We encode this criterion by including the hash in the cache's <code>key</code> (lines 31 and 40).</p> <p>Finally, we can use <code>if</code> to take a conditional step (line 46). The action, <code>actions/cache</code>, returns a Boolean to indicate if it found a cache. As a result, we can tell the workflow to install dependencies if the <code>yarn.lock</code> file changed.</p> <p>Thanks to caching, all jobs can now skip <code>yarn install</code>.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--6-3VQYea--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_4_github_actions.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--6-3VQYea--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_4_github_actions.png" alt="" width="800" height="667"></a></p> GitHub Actions can cache dependencies. <h1> 5. I Want to Take Percy Snapshots </h1> <p>The last problem that we want to solve is taking Percy snapshots (visual regression tests) <em>in parallel</em>.</p> <h2> a. Setup </h2> <p>If you haven't yet, make a new project in Percy. Link it to your GitHub repo by clicking on the Integrations tab. Finally, retrieve the project token, <code>PERCY_TOKEN</code>, by switching to Project settings tab.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--_Wo2XC9J--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_5a_percy.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--_Wo2XC9J--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_5a_percy.png" alt="" width="800" height="427"></a></p> Link the Percy project to your GitHub repo. <p>You can provide <code>PERCY_TOKEN</code> to GitHub by visiting your repo and clicking on the Settings tab. Find the submenu called Secrets.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--XkijW1_s--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_5a_github.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--XkijW1_s--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_5a_github.png" alt="" width="800" height="427"></a></p> Pass the Percy token to GitHub. <p>GitHub Actions can now access <code>PERCY_TOKEN</code> and send Percy snapshots.</p> <h2> b. First Attempt </h2> <p>Integrating Percy with GitHub Actions isn't too difficult. Percy documented the how-to well and even provides an action, <code>percy/exec-action</code>, to facilitate the workflow.</p> <p>Let's see what happens when we update the test step like this:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="c1"># File: .github/workflows/ci.yml</span> <span class="na">name</span><span class="pi">:</span> <span class="s">CI</span> <span class="na">on</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">push</span><span class="pi">,</span> <span class="nv">pull_request</span><span class="pi">]</span> <span class="na">jobs</span><span class="pi">:</span> <span class="na">lint</span><span class="pi">:</span> <span class="s">...</span> <span class="na">test-partition-1</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Run tests - Partition </span><span class="m">1</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="s">...</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test Ember app</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">percy/exec-action@v0.3.0</span> <span class="na">with</span><span class="pi">:</span> <span class="na">custom-command</span><span class="pi">:</span> <span class="s">yarn test --partition=1</span> <span class="na">env</span><span class="pi">:</span> <span class="na">PERCY_TOKEN</span><span class="pi">:</span> <span class="s">${{ secrets.PERCY_TOKEN }}</span> <span class="na">test-partition-2</span><span class="pi">:</span> <span class="s">...</span> <span class="na">test-partition-3</span><span class="pi">:</span> <span class="s">...</span> <span class="na">test-partition-4</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Run tests - Partition </span><span class="m">4</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="s">...</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test Ember app</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">percy/exec-action@v0.3.0</span> <span class="na">with</span><span class="pi">:</span> <span class="na">custom-command</span><span class="pi">:</span> <span class="s">yarn test --partition=4</span> <span class="na">env</span><span class="pi">:</span> <span class="na">PERCY_TOKEN</span><span class="pi">:</span> <span class="s">${{ secrets.PERCY_TOKEN }}</span> </code></pre> </div> <p>We need to change the <code>test</code> script one last time. Let's prepend <code>percy exec --</code>. It allows Percy to start and stop around the supplied command.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="err">#</span> <span class="nx">File</span><span class="p">:</span> <span class="kr">package</span><span class="p">.</span><span class="nx">json</span> <span class="p">{</span> <span class="p">...</span> <span class="dl">"</span><span class="s2">scripts</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="dl">"</span><span class="s2">build</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember build --environment=production</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:dependency</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember dependency-lint</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:hbs</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember-template-lint .</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">lint:js</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">eslint .</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">start</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">ember serve</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">test</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">percy exec -- ember exam --query=nolint --split=4 --parallel=1</span><span class="dl">"</span> <span class="p">}</span> <span class="p">...</span> <span class="p">}</span> </code></pre> </div> <p>When we commit the changes, the tests for Ember will continue to pass. However, Percy will think that we made 4 builds rather than 1. It's hard to tell which of the four holds the "truth." Maybe none do.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--STh2h1Op--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_5b_percy_incorrect_setup.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--STh2h1Op--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_5b_percy_incorrect_setup.png" alt="" width="800" height="480"></a></p> Multiple Percy builds occur if we naively implement the parallel workflow. <p>This problem occurs when we run tests in parallel. We need to tell Percy somehow that there are 4 jobs for testing and the snapshots belong to the same build.</p> <h2> c. Orchestrate </h2> <p>Luckily, we can use Percy's environment variables to coordinate snapshots. Setting <code>PERCY_PARALLEL_TOTAL</code>, the number of parallel build nodes, is easy in my case. It's always 4. But what about <code>PERCY_PARALLEL_NONCE</code>, a unique identifier for the build?</p> <p>GitHub keeps track of two variables, <code>run_id</code> and <code>run_number</code>, for your repo. The former is a number for each run in the repo (e.g. 56424940, 57489786, 57500258), while the latter is a number for each run of a particular workflow in the repo (e.g. 44, 45, 46). Just to be safe, I combined the two to arrive at a nonce.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight yaml"><code><span class="c1"># File: .github/workflows/ci.yml</span> <span class="na">name</span><span class="pi">:</span> <span class="s">CI</span> <span class="na">on</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">push</span><span class="pi">,</span> <span class="nv">pull_request</span><span class="pi">]</span> <span class="na">env</span><span class="pi">:</span> <span class="na">PERCY_PARALLEL_NONCE</span><span class="pi">:</span> <span class="s">${{ github.run_id }}-${{ github.run_number }}</span> <span class="na">jobs</span><span class="pi">:</span> <span class="na">lint</span><span class="pi">:</span> <span class="s">...</span> <span class="na">test-partition-1</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Run tests - Partition </span><span class="m">1</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="s">...</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test Ember app</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">percy/exec-action@v0.3.0</span> <span class="na">with</span><span class="pi">:</span> <span class="na">custom-command</span><span class="pi">:</span> <span class="s">yarn test --partition=1</span> <span class="na">env</span><span class="pi">:</span> <span class="na">PERCY_PARALLEL_NONCE</span><span class="pi">:</span> <span class="s">${{ env.PERCY_PARALLEL_NONCE }}</span> <span class="na">PERCY_PARALLEL_TOTAL</span><span class="pi">:</span> <span class="m">4</span> <span class="na">PERCY_TOKEN</span><span class="pi">:</span> <span class="s">${{ secrets.PERCY_TOKEN }}</span> <span class="na">test-partition-2</span><span class="pi">:</span> <span class="s">...</span> <span class="na">test-partition-3</span><span class="pi">:</span> <span class="s">...</span> <span class="na">test-partition-4</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Run tests - Partition </span><span class="m">4</span> <span class="na">runs-on</span><span class="pi">:</span> <span class="s">${{ matrix.os }}</span> <span class="na">strategy</span><span class="pi">:</span> <span class="na">matrix</span><span class="pi">:</span> <span class="na">os</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">ubuntu-latest</span><span class="pi">]</span> <span class="na">node-version</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">12.x</span><span class="pi">]</span> <span class="na">steps</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Check out a copy of the repo</span> <span class="s">...</span> <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Test Ember app</span> <span class="na">uses</span><span class="pi">:</span> <span class="s">percy/exec-action@v0.3.0</span> <span class="na">with</span><span class="pi">:</span> <span class="na">custom-command</span><span class="pi">:</span> <span class="s">yarn test --partition=4</span> <span class="na">env</span><span class="pi">:</span> <span class="na">PERCY_PARALLEL_NONCE</span><span class="pi">:</span> <span class="s">${{ env.PERCY_PARALLEL_NONCE }}</span> <span class="na">PERCY_PARALLEL_TOTAL</span><span class="pi">:</span> <span class="m">4</span> <span class="na">PERCY_TOKEN</span><span class="pi">:</span> <span class="s">${{ secrets.PERCY_TOKEN }}</span> </code></pre> </div> <p>Once you introduce these environment variables, Percy will group the snapshots to a single build.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s---LwdG_HW--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_5b_percy_correct_setup.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s---LwdG_HW--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_5b_percy_correct_setup.png" alt="" width="800" height="320"></a></p> A single Percy build occurs when we implement the parallel workflow right. <h1> 6. Conclusion </h1> <p>Overall, I had a great time figuring out how to write a CI workflow for Ember apps in GitHub Actions. Writing code helped me understand better the steps involved in a CI. Not all was great, though. The documentation for caching can definitely use help with showing clear, exhaustive examples.</p> <p>At any rate, now, I can sit back and enjoy the benefits of linting and running tests with every commit. I'm looking forward to see what <a href="https://ember-music.herokuapp.com/">Ember Music</a> will turn into.</p> <p><a href="https://res.cloudinary.com/practicaldev/image/fetch/s--o55fOyvm--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_6_badges.png" class="article-body-image-wrapper"><img src="https://res.cloudinary.com/practicaldev/image/fetch/s--o55fOyvm--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_800/https://crunchingnumbersdotlive.files.wordpress.com/2020/03/section_6_badges.png" alt="" width="800" height="224"></a></p> You made it! Give yourself some badges. <h1> Notes </h1> <p>You can find my CI workflow for Ember apps on GitHub Gist (<a href="https://gist.github.com/ijlee2/2e7be877ceb60b9fa7c80298121d1024">yarn</a>, <a href="https://gist.github.com/ijlee2/030df226d02e32f6e4311591f58d87f8">npm</a>). It works for all operating systems: Linux, Mac, and Windows.</p> <p>In <code>testem.js</code>, you will see a reference to <code>process.env.CI</code>:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight javascript"><code><span class="c1">// File: testem.js</span> <span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="p">{</span> <span class="na">test_page</span><span class="p">:</span> <span class="dl">'</span><span class="s1">tests/index.html?hidepassed</span><span class="dl">'</span><span class="p">,</span> <span class="p">...</span> <span class="na">browser_args</span><span class="p">:</span> <span class="p">{</span> <span class="na">Chrome</span><span class="p">:</span> <span class="p">{</span> <span class="na">ci</span><span class="p">:</span> <span class="p">[</span> <span class="c1">// --no-sandbox is needed when running Chrome inside a container</span> <span class="nx">process</span><span class="p">.</span><span class="nx">env</span><span class="p">.</span><span class="nx">CI</span> <span class="p">?</span> <span class="dl">'</span><span class="s1">--no-sandbox</span><span class="dl">'</span> <span class="p">:</span> <span class="kc">null</span><span class="p">,</span> <span class="dl">'</span><span class="s1">--headless</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">--disable-dev-shm-usage</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">--disable-software-rasterizer</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">--mute-audio</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">--remote-debugging-port=0</span><span class="dl">'</span><span class="p">,</span> <span class="dl">'</span><span class="s1">--window-size=1440,900</span><span class="dl">'</span> <span class="p">].</span><span class="nx">filter</span><span class="p">(</span><span class="nb">Boolean</span><span class="p">)</span> <span class="p">}</span> <span class="p">}</span> <span class="p">};</span> </code></pre> </div> <p>I'm not sure where <code>--no-sandbox</code> gets used (this <a href="https://www.google.com/googlebooks/chrome/med_26.html">comic</a> explains <strong>sandbox</strong>) and haven't found a need for it yet. If you need it for CI, please check the <code>ember-animated</code> example below. It seems, at the job level, you can set the environment variable.</p> <p>I would like to know more about the history of and need for <code>--no-sandbox</code>.</p> <h2> Resources </h2> <p>If you want to learn more about GitHub Actions, Ember Exam, and Percy, I encourage you to visit these links:</p> <h3> GitHub Actions </h3> <ul> <li><a href="https://help.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-actions">About Billing for GitHub Actions</a></li> <li><a href="https://help.github.com/actions/configuring-and-managing-workflows/configuring-a-workflow">Configuring a Workflow</a></li> <li><a href="https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions">Using Node.js with GitHub Actions</a></li> <li><a href="https://help.github.com/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows">Caching Dependencies to Speed Up Workflows</a></li> <li><a href="https://github.com/actions/cache/blob/master/examples.md#node---npm">Cache Implementation for <code>npm</code></a></li> <li><a href="https://github.com/actions/cache/blob/master/examples.md#node---yarn">Cache Implementation for <code>yarn</code></a></li> </ul> <h3> Ember Exam </h3> <ul> <li><a href="https://ember-cli.com/ember-exam/docs">Quickstart</a></li> </ul> <h3> Percy </h3> <ul> <li><a href="https://docs.percy.io/docs/github-actions">GitHub Actions</a></li> <li><a href="https://docs.percy.io/docs/parallel-test-suites">Parallel Test Suites</a></li> </ul> <h3> Workflow Examples </h3> <ul> <li><a href="https://github.com/microsoft/chart-parts/blob/master/.github/workflows/ci.yml">chart-parts</a></li> <li><a href="https://github.com/ember-animation/ember-animated/blob/master/.github/workflows/nodejs.yml">ember-animated</a></li> <li><a href="https://github.com/NullVoxPopuli/emberclear/blob/master/.github/workflows/frontend-tests.yml">ember-clear</a></li> <li><a href="https://github.com/ember-cli/ember-cli-htmlbars/blob/master/.github/workflows/ci.yml">ember-cli-htmlbars</a></li> <li><a href="https://github.com/glimmerjs/glimmer.js/blob/master/.github/workflows/ci.yml">glimmer.js</a></li> </ul> ember javascript ci showdev