Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update migration docs for adopting native types in 6.1 #1001

Merged
merged 2 commits into from
Dec 21, 2022
Merged

Update migration docs for adopting native types in 6.1 #1001

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7c48960
Update migration docs for adopting native types in 6.1
dfreeman Dec 21, 2022
66db2bc
Update `@ember/test-helpers` and drop unneeded `@glimmer` devDeps
dfreeman Dec 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 38 additions & 22 deletions docs/migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,49 +4,65 @@ Migration Guide

Migrating to native TypeScript support in v6.1.0
------------------------------------------------------------------------------
The types for the QUnit `TestContext` provided by the `ember-qunit` and `@ember/test-helpers` types on DefinitelyTyped made a choice to prioritize convenience over robustness when it came to what methods and values were available on `this` in any given test: they made _all_ methods availabe regardless of what your setup actually involved.

The types for the QUnit `TestContext` provided by the `ember-qunit` and `@ember/test-helpers` types on DefinitelyTyped made a choice to prioritize convenience over robustness when it came to what methods and values were available on `this` in any given test: they made *all* methods availabe regardless of what your setup actually involved. For example, this totally invalid code would have passed the type checker:
If your tests rely on properties of `this` that aren't actually available in all test contexts, like `this.render` or `this.element`, those tests will now produce type errors.

For example, with the 6.1 native types, this test would produce a type error on the line where `this.element` is referenced:

```ts
import { module, test } from 'qunit';
import { setupTest } from 'ember-qunit';
import { setupRenderingTest } from 'ember-qunit';
import { hbs } from 'ember-cli-htmlbars';

module('bad times', function (hooks) {
setupTest(hooks);
module('<Greeting />', function (hooks) {
setupRenderingTest(hooks);

test('this will not *run* correctly', async function (assert) {
await this.render(hbs`<p>whoopsie</p>`);
test('greets', async function (assert) {
await render(hbs`<Greeting />`);
assert.equal(this.element.textContent?.trim(), 'Hello!');
});
})
});
```

To resolve this, you need to explicitly specify what `this` is for different kinds of tests:
To resolve this, you can explicitly specify what `this` is for different kinds of tests:

```ts
import { module, test } from 'qunit';
import { setupTest } from 'ember-qunit';
import type { RenderingTextContext } from '@ember/test-helpers';
import { setupRenderingTest } from 'ember-qunit';
import { hbs } from 'ember-cli-htmlbars';
import type { RenderingTextContext } from '@ember/test-helpers';

module('better times', function (hooks) {
setupTest(hooks);
module('<Greeting />', function (hooks) {
setupRenderingTest(hooks);

test(
'this will not *run* correctly',
async function (this: RenderingTextContext, assert) {
await this.render(hbs`<p>whoopsie</p>`);
}
);
})
test('greets', async function (this: RenderingTestContext, assert) {
await render(hbs`<Greeting />`);
assert.equal(this.element.textContent?.trim(), 'Hello!');
});
});
```

While annoying, this is accurate and prevents the annoying mismatch. Combined with support for using local scope with `<template>` (see [Ember RFC 0785][rfc-0785]), available since v2.8 of `@ember/test-helpers`, the need to specify the `this` will go away entirely over time.
In many cases this should not be necessary, though. For instance, if the test above were written using [`qunit-dom`][qunit-dom] instead, no `this` annotation would be needed:

```ts
import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { hbs } from 'ember-cli-htmlbars';

module('<Greeting />', function (hooks) {
setupRenderingTest(hooks);

[rfc-0785]: https://rfcs.emberjs.com/id/0785-remove-set-get-in-tests
test('greets', async function (assert) {
await render(hbs`<Greeting />`);
assert.dom().hasText('Hello!');
});
});
```

To use these public types, you also will need to add `@glimmer/interfaces` and `@glimmer/reference` to your `devDependencies`, since of `@ember/test-helpers` uses them (indirectly) in its public APIs, and `ember-qunit` uses `@ember/test-helpers` in turn.
[qunit-dom]: https://github.com/mainmatter/qunit-dom

While annoying, the tighter default type for `this` in tests is accurate and prevents TypeScript from presenting invalid options while authoring tests. Combined with support for using local scope with `<template>` (see [Ember RFC 0785][rfc-0785]), available since v2.8 of `@ember/test-helpers`, the need to specify the `this` will go away entirely over time.

Upgrading from v4.x to v5.0.0
------------------------------------------------------------------------------
Expand Down
4 changes: 1 addition & 3 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,9 @@
"@babel/core": "^7.20.5",
"@babel/eslint-parser": "^7.19.1",
"@ember/optional-features": "^2.0.0",
"@ember/test-helpers": "^2.9.1",
"@ember/test-helpers": "^2.9.3",
"@embroider/test-setup": "^2.0.2",
"@glimmer/component": "^1.1.2",
"@glimmer/interfaces": "^0.84.2",
"@glimmer/reference": "^0.84.2",
"@tsconfig/ember": "^1.1.0",
"@types/qunit": "^2.19.3",
"@types/rsvp": "^4.0.4",
Expand Down
2 changes: 0 additions & 2 deletions types/tests.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,6 @@ module('rendering', function (hooks) {
this.render();
// @ts-expect-error
this.render('{{ x-foo value=value action="result" }}');
// @ts-expect-error
this.render(['{{ x-foo value=value action="result" }}']);

const el = this.element.querySelector('div');
assert.equal(el?.innerText, 'cat', 'The component shows the correct value');
Expand Down
57 changes: 5 additions & 52 deletions yarn.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1022,10 +1022,10 @@
mkdirp "^1.0.4"
silent-error "^1.1.1"

"@ember/test-helpers@^2.9.1":
version "2.9.1"
resolved "https://registry.yarnpkg.com/@ember/test-helpers/-/test-helpers-2.9.1.tgz#142a8d5175fc79bb328b7af0cd36755c10181050"
integrity sha512-1ZFZCnNfkXcQOf6Vxep/vbZMwFLfD+8heiLiQ6LSB5SY9F3VCF1yNslfgtDqmyQZXhAbbhRTDhy+rHuzzpd+yA==
"@ember/test-helpers@^2.9.3":
version "2.9.3"
resolved "https://registry.yarnpkg.com/@ember/test-helpers/-/test-helpers-2.9.3.tgz#c2a9d6ab1c367af92cf1a334f97eb19b8e06e6e1"
integrity sha512-ejVg4Dj+G/6zyLvQsYOvmGiOLU6AS94tY4ClaO1E2oVvjjtVJIRmVLFN61I+DuyBg9hS3cFoPjQRTZB9MRIbxQ==
dependencies:
"@ember/test-waiters" "^3.0.0"
"@embroider/macros" "^1.10.0"
Expand Down Expand Up @@ -1136,58 +1136,16 @@
resolved "https://registry.yarnpkg.com/@glimmer/di/-/di-0.1.11.tgz#a6878c07a13a2c2c76fcde598a5c97637bfc4280"
integrity sha512-moRwafNDwHTnTHzyyZC9D+mUSvYrs1Ak0tRPjjmCghdoHHIvMshVbEnwKb/1WmW5CUlKc2eL9rlAV32n3GiItg==

"@glimmer/env@0.1.7", "@glimmer/env@^0.1.7":
"@glimmer/env@^0.1.7":
version "0.1.7"
resolved "https://registry.yarnpkg.com/@glimmer/env/-/env-0.1.7.tgz#fd2d2b55a9029c6b37a6c935e8c8871ae70dfa07"
integrity sha512-JKF/a9I9jw6fGoz8kA7LEQslrwJ5jms5CXhu/aqkBWk+PmZ6pTl8mlb/eJ/5ujBGTiQzBhy5AIWF712iA+4/mw==

"@glimmer/[email protected]":
version "0.84.2"
resolved "https://registry.yarnpkg.com/@glimmer/global-context/-/global-context-0.84.2.tgz#cd4612925dbd68787b9270e91b213691150c307f"
integrity sha512-6FycLh/Eq0P3LA94bJL6WHPJyOTKeQD4KBWhowZ9TbeO3p4/WUr+POKPVEyfIx6YHybhpL9MGj45Y2r0hqVigw==
dependencies:
"@glimmer/env" "^0.1.7"

"@glimmer/[email protected]", "@glimmer/interfaces@^0.84.2":
version "0.84.2"
resolved "https://registry.yarnpkg.com/@glimmer/interfaces/-/interfaces-0.84.2.tgz#764cf92c954adcd1a851e5dc68ec1f6b654dc3bd"
integrity sha512-tMZxQpOddUVmHEOuripkNqVR7ba0K4doiYnFd4WyswqoHPlxqpBujbIamQ+bWCWEF0U4yxsXKa31ekS/JHkiBQ==
dependencies:
"@simple-dom/interface" "^1.4.0"

"@glimmer/reference@^0.84.2":
version "0.84.2"
resolved "https://registry.yarnpkg.com/@glimmer/reference/-/reference-0.84.2.tgz#c8d91a3ba0b92a9430b6023d7b6f39dd56c79af1"
integrity sha512-hH0VD76OXMsGSHbqaqD64u1aBEqy//jhZtIaHGwAHNpTEX+zDtW3ka298KbAn2CZyDDrNAnuc2U1Vy4COR3zlA==
dependencies:
"@glimmer/env" "^0.1.7"
"@glimmer/global-context" "0.84.2"
"@glimmer/interfaces" "0.84.2"
"@glimmer/util" "0.84.2"
"@glimmer/validator" "0.84.2"

"@glimmer/[email protected]":
version "0.84.2"
resolved "https://registry.yarnpkg.com/@glimmer/util/-/util-0.84.2.tgz#2711ba40f25f44b2ea309cad49f5c2622c6211bc"
integrity sha512-VbhzE2s4rmU+qJF3gGBTL1IDjq+/G2Th51XErS8MQVMCmE4CU2pdwSzec8PyOowqCGUOrVIWuMzEI6VoPM4L4w==
dependencies:
"@glimmer/env" "0.1.7"
"@glimmer/interfaces" "0.84.2"
"@simple-dom/interface" "^1.4.0"

"@glimmer/util@^0.44.0":
version "0.44.0"
resolved "https://registry.yarnpkg.com/@glimmer/util/-/util-0.44.0.tgz#45df98d73812440206ae7bda87cfe04aaae21ed9"
integrity sha512-duAsm30uVK9jSysElCbLyU6QQYO2X9iLDLBIBUcCqck9qN1o3tK2qWiHbGK5d6g8E2AJ4H88UrfElkyaJlGrwg==

"@glimmer/[email protected]":
version "0.84.2"
resolved "https://registry.yarnpkg.com/@glimmer/validator/-/validator-0.84.2.tgz#29394d262cf8373fe20f4e225c1adc9857a4164b"
integrity sha512-9tpSmwiktsJDqriNEiFfyP+9prMSdk08THA6Ik71xS/sudBKxoDpul678uvyEYST/+Z23F8MxwKccC+QxCMXNA==
dependencies:
"@glimmer/env" "^0.1.7"
"@glimmer/global-context" "0.84.2"

"@glimmer/[email protected]":
version "0.84.2"
resolved "https://registry.yarnpkg.com/@glimmer/vm-babel-plugins/-/vm-babel-plugins-0.84.2.tgz#653ce82a6656b4396d87a479d8699450d35a17f0"
Expand Down Expand Up @@ -1439,11 +1397,6 @@
"@pnpm/network.ca-file" "^1.0.1"
config-chain "^1.1.11"

"@simple-dom/interface@^1.4.0":
version "1.4.0"
resolved "https://registry.yarnpkg.com/@simple-dom/interface/-/interface-1.4.0.tgz#e8feea579232017f89b0138e2726facda6fbb71f"
integrity sha512-l5qumKFWU0S+4ZzMaLXFU8tQZsicHEMEyAxI5kDFGhJsRqDwe0a7/iPA/GdxlGyDKseQQAgIz5kzU7eXTrlSpA==

"@sindresorhus/is@^0.14.0":
version "0.14.0"
resolved "https://registry.yarnpkg.com/@sindresorhus/is/-/is-0.14.0.tgz#9fb3a3cf3132328151f353de4632e01e52102bea"
Expand Down