Skip to content

Commit 5f14aa8

Browse files
authored
Merge pull request #1001 from dfreeman/update-migration-notes-for-native-types
Update migration docs for adopting native types in 6.1
2 parents 4782daf + 66db2bc commit 5f14aa8

File tree

4 files changed

+44
-79
lines changed

4 files changed

+44
-79
lines changed

docs/migration.md

+38-22
Original file line numberDiff line numberDiff line change
@@ -4,49 +4,65 @@ Migration Guide
44

55
Migrating to native TypeScript support in v6.1.0
66
------------------------------------------------------------------------------
7+
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.
78

8-
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:
9+
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.
10+
11+
For example, with the 6.1 native types, this test would produce a type error on the line where `this.element` is referenced:
912

1013
```ts
1114
import { module, test } from 'qunit';
12-
import { setupTest } from 'ember-qunit';
15+
import { setupRenderingTest } from 'ember-qunit';
1316
import { hbs } from 'ember-cli-htmlbars';
1417

15-
module('bad times', function (hooks) {
16-
setupTest(hooks);
18+
module('<Greeting />', function (hooks) {
19+
setupRenderingTest(hooks);
1720

18-
test('this will not *run* correctly', async function (assert) {
19-
await this.render(hbs`<p>whoopsie</p>`);
21+
test('greets', async function (assert) {
22+
await render(hbs`<Greeting />`);
23+
assert.equal(this.element.textContent?.trim(), 'Hello!');
2024
});
21-
})
25+
});
2226
```
2327

24-
To resolve this, you need to explicitly specify what `this` is for different kinds of tests:
28+
To resolve this, you can explicitly specify what `this` is for different kinds of tests:
2529

2630
```ts
2731
import { module, test } from 'qunit';
28-
import { setupTest } from 'ember-qunit';
29-
import type { RenderingTextContext } from '@ember/test-helpers';
32+
import { setupRenderingTest } from 'ember-qunit';
3033
import { hbs } from 'ember-cli-htmlbars';
34+
import type { RenderingTextContext } from '@ember/test-helpers';
3135

32-
module('better times', function (hooks) {
33-
setupTest(hooks);
36+
module('<Greeting />', function (hooks) {
37+
setupRenderingTest(hooks);
3438

35-
test(
36-
'this will not *run* correctly',
37-
async function (this: RenderingTextContext, assert) {
38-
await this.render(hbs`<p>whoopsie</p>`);
39-
}
40-
);
41-
})
39+
test('greets', async function (this: RenderingTestContext, assert) {
40+
await render(hbs`<Greeting />`);
41+
assert.equal(this.element.textContent?.trim(), 'Hello!');
42+
});
43+
});
4244
```
4345

44-
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.
46+
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:
47+
48+
```ts
49+
import { module, test } from 'qunit';
50+
import { setupRenderingTest } from 'ember-qunit';
51+
import { hbs } from 'ember-cli-htmlbars';
52+
53+
module('<Greeting />', function (hooks) {
54+
setupRenderingTest(hooks);
4555

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

48-
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.
63+
[qunit-dom]: https://github.com/mainmatter/qunit-dom
4964

65+
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.
5066

5167
Upgrading from v4.x to v5.0.0
5268
------------------------------------------------------------------------------

package.json

+1-3
Original file line numberDiff line numberDiff line change
@@ -49,11 +49,9 @@
4949
"@babel/core": "^7.20.5",
5050
"@babel/eslint-parser": "^7.19.1",
5151
"@ember/optional-features": "^2.0.0",
52-
"@ember/test-helpers": "^2.9.1",
52+
"@ember/test-helpers": "^2.9.3",
5353
"@embroider/test-setup": "^2.0.2",
5454
"@glimmer/component": "^1.1.2",
55-
"@glimmer/interfaces": "^0.84.2",
56-
"@glimmer/reference": "^0.84.2",
5755
"@tsconfig/ember": "^1.1.0",
5856
"@types/qunit": "^2.19.3",
5957
"@types/rsvp": "^4.0.4",

types/tests.ts

-2
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,6 @@ module('rendering', function (hooks) {
4141
this.render();
4242
// @ts-expect-error
4343
this.render('{{ x-foo value=value action="result" }}');
44-
// @ts-expect-error
45-
this.render(['{{ x-foo value=value action="result" }}']);
4644

4745
const el = this.element.querySelector('div');
4846
assert.equal(el?.innerText, 'cat', 'The component shows the correct value');

yarn.lock

+5-52
Original file line numberDiff line numberDiff line change
@@ -1022,10 +1022,10 @@
10221022
mkdirp "^1.0.4"
10231023
silent-error "^1.1.1"
10241024

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

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

1144-
"@glimmer/[email protected]":
1145-
version "0.84.2"
1146-
resolved "https://registry.yarnpkg.com/@glimmer/global-context/-/global-context-0.84.2.tgz#cd4612925dbd68787b9270e91b213691150c307f"
1147-
integrity sha512-6FycLh/Eq0P3LA94bJL6WHPJyOTKeQD4KBWhowZ9TbeO3p4/WUr+POKPVEyfIx6YHybhpL9MGj45Y2r0hqVigw==
1148-
dependencies:
1149-
"@glimmer/env" "^0.1.7"
1150-
1151-
"@glimmer/[email protected]", "@glimmer/interfaces@^0.84.2":
1152-
version "0.84.2"
1153-
resolved "https://registry.yarnpkg.com/@glimmer/interfaces/-/interfaces-0.84.2.tgz#764cf92c954adcd1a851e5dc68ec1f6b654dc3bd"
1154-
integrity sha512-tMZxQpOddUVmHEOuripkNqVR7ba0K4doiYnFd4WyswqoHPlxqpBujbIamQ+bWCWEF0U4yxsXKa31ekS/JHkiBQ==
1155-
dependencies:
1156-
"@simple-dom/interface" "^1.4.0"
1157-
1158-
"@glimmer/reference@^0.84.2":
1159-
version "0.84.2"
1160-
resolved "https://registry.yarnpkg.com/@glimmer/reference/-/reference-0.84.2.tgz#c8d91a3ba0b92a9430b6023d7b6f39dd56c79af1"
1161-
integrity sha512-hH0VD76OXMsGSHbqaqD64u1aBEqy//jhZtIaHGwAHNpTEX+zDtW3ka298KbAn2CZyDDrNAnuc2U1Vy4COR3zlA==
1162-
dependencies:
1163-
"@glimmer/env" "^0.1.7"
1164-
"@glimmer/global-context" "0.84.2"
1165-
"@glimmer/interfaces" "0.84.2"
1166-
"@glimmer/util" "0.84.2"
1167-
"@glimmer/validator" "0.84.2"
1168-
1169-
"@glimmer/[email protected]":
1170-
version "0.84.2"
1171-
resolved "https://registry.yarnpkg.com/@glimmer/util/-/util-0.84.2.tgz#2711ba40f25f44b2ea309cad49f5c2622c6211bc"
1172-
integrity sha512-VbhzE2s4rmU+qJF3gGBTL1IDjq+/G2Th51XErS8MQVMCmE4CU2pdwSzec8PyOowqCGUOrVIWuMzEI6VoPM4L4w==
1173-
dependencies:
1174-
"@glimmer/env" "0.1.7"
1175-
"@glimmer/interfaces" "0.84.2"
1176-
"@simple-dom/interface" "^1.4.0"
1177-
11781144
"@glimmer/util@^0.44.0":
11791145
version "0.44.0"
11801146
resolved "https://registry.yarnpkg.com/@glimmer/util/-/util-0.44.0.tgz#45df98d73812440206ae7bda87cfe04aaae21ed9"
11811147
integrity sha512-duAsm30uVK9jSysElCbLyU6QQYO2X9iLDLBIBUcCqck9qN1o3tK2qWiHbGK5d6g8E2AJ4H88UrfElkyaJlGrwg==
11821148

1183-
"@glimmer/[email protected]":
1184-
version "0.84.2"
1185-
resolved "https://registry.yarnpkg.com/@glimmer/validator/-/validator-0.84.2.tgz#29394d262cf8373fe20f4e225c1adc9857a4164b"
1186-
integrity sha512-9tpSmwiktsJDqriNEiFfyP+9prMSdk08THA6Ik71xS/sudBKxoDpul678uvyEYST/+Z23F8MxwKccC+QxCMXNA==
1187-
dependencies:
1188-
"@glimmer/env" "^0.1.7"
1189-
"@glimmer/global-context" "0.84.2"
1190-
11911149
"@glimmer/[email protected]":
11921150
version "0.84.2"
11931151
resolved "https://registry.yarnpkg.com/@glimmer/vm-babel-plugins/-/vm-babel-plugins-0.84.2.tgz#653ce82a6656b4396d87a479d8699450d35a17f0"
@@ -1439,11 +1397,6 @@
14391397
"@pnpm/network.ca-file" "^1.0.1"
14401398
config-chain "^1.1.11"
14411399

1442-
"@simple-dom/interface@^1.4.0":
1443-
version "1.4.0"
1444-
resolved "https://registry.yarnpkg.com/@simple-dom/interface/-/interface-1.4.0.tgz#e8feea579232017f89b0138e2726facda6fbb71f"
1445-
integrity sha512-l5qumKFWU0S+4ZzMaLXFU8tQZsicHEMEyAxI5kDFGhJsRqDwe0a7/iPA/GdxlGyDKseQQAgIz5kzU7eXTrlSpA==
1446-
14471400
"@sindresorhus/is@^0.14.0":
14481401
version "0.14.0"
14491402
resolved "https://registry.yarnpkg.com/@sindresorhus/is/-/is-0.14.0.tgz#9fb3a3cf3132328151f353de4632e01e52102bea"

0 commit comments

Comments
 (0)