Advance RFC #0726 "DOM Element descriptor interface for test helpers" to Stage Ready for Release

[emberjs-rfcs-bot]

Advance #726 to the Ready For Release Stage

Rendered

Summary

This pull request is advancing the RFC to the Ready For Release Stage.

• PR to Accepted Stage: DOM Element descriptor interface for test helpers #726

An FCP is required before merging this PR to advance.

Upon merging this PR, automation will open a draft PR for this RFC to move to the Released Stage.

Ready for Release Stage Description

This stage is complete when the implementation is complete according to plan outlined in the RFC, and is in harmony with any changes in Ember that have occurred since the RFC was first written. This includes any necessary learning materials. At this stage, features or deprecations may be available for use behind a feature flag, or with an optional package, etc.

For codebase changes, there are no open questions that are anticipated to require breaking changes; the Ember team is ready to commit to the stability of any interfaces exposed by the current implementation of the feature.

This stage should include a list of criteria for determining when the proposal can be considered Recommended after being Released.

An FCP is required to move into this stage.

Each Ember core team will be requested as a reviewer on the PR to move into this stage. A representative of each team adds a review. If a team does not respond to the request, and after the conclusion of the FCP, it is assumed that the release may proceed.

Checklist to move to Ready for Release

• Implementation is complete according to plan outlined in the RFC, with any adjustments noted in the RFC
• Any necessary learning materials have been updated
• The Ember team is ready to commit to the stability of any interfaces exposed by the current implementation of the feature. This is the go/no go decision for any feature flags, but the flags should only be turned on when moving to Released.
• Criteria for moving to the Recommended Stage has been filled out
• This PR has been converted from a draft to a regular PR and the Final Comment Period label has been added to start the FCP
• Each team has been added as a reviewer to the PR at the start of the FCP. Reviews are not required by the end of the FCP. This is a notification step.
  • Framework @emberjs/framework
  • Data @emberjs/ember-data-core
  • CLI @emberjs/cli
  • Learning @emberjs/learning-core
  • Typescript @emberjs/typescript-core
  • Steering @emberjs/steering

Criteria for moving to Recommended (required)

A set of criteria for moving this RFC to the Recommended Stage, following release:

We discussed documentation requirements and agreed that including this in the appropriate repo README's is sufficient. It doesn't need to get added to the guide / tutorial. So the criterion is just reviewing those READMEs. The feature is purely additive and doesn't depend on any in-flight features so we don't see any additional blockers for Recommended.

• review the relevant repo README's

Track Implementation

• The dom-element-descriptors library
• An @ember/test-helpers Support passing IDOMElementDescriptors as targets ember-test-helpers#1446 added support for passing IDOMElementDescriptors to the DOM helpers (click, triggerEvent, etc)
• A qunit-dom feature: support IDOMElementDescriptors mainmatter/qunit-dom#2087 adding support for passing IDOMElementDescriptors to qunit.dom()
• A fractal-page-object Implement DOM element descriptors bendemboski/fractal-page-object#114 PR registering page objects as descriptors, and implementing tests validating the full end-to-end integration of all four libraries

[ef4]

@bendemboski could you please look this over and fill out the criteria for calling this RFC "Recommended"?

[ef4]

Also, if implementation work has already shipped or is in flight it would be good to link PRs here.

[bendemboski]

@ef4 does something need to happen to give me permissions to edit the PR description? Or is there some other process for me to provide this info that I'm not seeing?

[ef4]

Oh yeah, please just comment instead of edit and we can figure that out.

[bendemboski]

Implementation tracking:

• The dom-element-descriptors library
• An @ember/test-helpers draft PR added support for passing IDOMElementDescriptors to the DOM helpers (click, triggerEvent, etc)
• A qunit-dom draft PR adding support for passing IDOMElementDescriptors to qunit.dom()
• I'm working on a PR in fractal-page-object

[ef4]

@bendemboski are there any blockers we can help with on the implementation here?

[bendemboski]

@ef4 I don't think so -- I've not had much time for OSS lately, but should soon be able to get the fractal-page-object work done, and then once I have a test app in fractal-page-object proving the integrated story (dom-element-descriptors + @ember/test-helpers + qunit-dom + fractal-page-object), we can start working on getting the various PRs merged.

At least that's my current plan, but open to feedback!

[bendemboski]

@ef4 the implementations are all complete in the various PRs, described above. I think I need a little help with the criteria for moving to recommended...I guess I'm just not familiar enough with the process to know what they should be.

Certainly all the PRs need to be merged and released, including documentation in each of the individual projects. We had discussed some documentation in the Ember guides, but not until/unless we decide that they should start recommending the page object pattern. I guess there should be some period of hardening -- usage, feedback, bug fixes & improvements -- before this would become recommended.

So I think next steps here are:

1. Somebody help me figure out the criteria for moving to recommended
2. Convert the qunit-dom and @ember/test-helpers PRs from draft to ready-to-merge, and do whatever is needed to get them merged
3. Update the fractal-page-object branch to have the test app consume the published versions of those two packages, rather than patching them, and merge and release it.

Make sense? How can we do (1)?

I'm hoping to join the 11am Pacific RFC review call tomorrow, but I'm not totally sure I'll be able to.