CT Public API docs #5069

lmiller1990 · 2023-02-16T04:59:20Z

Docs for the new Framework Definitions feature. Epic: cypress-io/cypress#25637 (linked to all relevant issues).

vercel · 2023-02-16T04:59:23Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated
cypress-documentation	✅ Ready (Inspect)	Visit Preview	💬 Add your feedback	Feb 24, 2023 at 8:06PM (UTC)

mike-plummer

Couple wording suggestions and questions, but overall this is awesome content!

One total nitpick - the screenshots have 12.6.0 but this feature is marked as 12.7+

docs/guides/component-testing/third-party-definitions.mdx

elylucas · 2023-02-17T16:17:14Z

We should probably update the supported frameworks to also mention community libraries with a link to this guide and link to a list of community libs.

Where would be a good place to list the community libraries in the docs? My initial thoughts is we can remove the older CT libs from the component testing section in plugins and list them there.

docs/guides/component-testing/third-party-definitions.mdx

elylucas · 2023-02-17T15:48:50Z

docs/guides/component-testing/third-party-definitions.mdx

+
+The second part of defining a Framework Definition is the Mount Adapter. This is the function that renders the component in your tests using `cy.mount()`. 
+
+By default, Cypress will look for this as a `mount` function that is a **named export** from the package. This should be written in a `index.mjs` file. This example is for a [Solid.js](https://www.solidjs.com/) mount adapter:


I think we should be showing the examples in TypeScript and highly recommending that TS is used in their own libraries.

We might even think about putting together a starter template that someone could just clone and it would have building and bundling baked in.

Ahh, I see reading further down there is a template, but I think that should be updated to TypeScript with the build steps built in (like above). This will help ensure that the Typings get created and (🌶) all libs should be built in TS.

might be good to mention the template earlier in the guide as well

I did not do this initially since I thought it added quite a bit of complexity. The build step is a little messy. Cypress (the server component) will always require the CJS entry - in this case, definition.cjs. Both our bundlers (webpack and vite) want an ES module. We would need two separate build steps - one for the Node.js entry and one for the ESM entry.

I updated the template to have TypeScript by default. It has two tsconfig.json - one for the server entry (definition) and one for the mount entry (esm). Take a look and let me know what you think @elylucas: https://github.com/cypress-io/cypress-ct-definition-template

I also updated my own example to use this template: https://github.com/lmiller1990/cypress-ct-solid-js

docs/guides/component-testing/third-party-definitions.mdx

Co-authored-by: Ely Lucas <ely@meta-tek.net> Co-authored-by: Mike Plummer <mike-plummer@users.noreply.github.com>

lmiller1990 · 2023-02-20T05:41:07Z

docs/guides/component-testing/third-party-definitions.mdx

+
+## Testing
+
+If you develop the Framework Definition file using TypeScript, for example by using [our official template](https://github.com/cypress-io/cypress-ct-definition-template), as long as you don't have any compile time errors, everything should work as expected. If you do run into unexpected behavior, please [file an issue](https://github.com/cypress-io/cypress/issues).


Worth noting we've got better warnings for definitions coming VERY soon (next sprint) cypress-io/cypress#25838 but they are not supported right now. The issue requires the docs to be updated when they are added.

lmiller1990

@elylucas @mike-plummer thanks for the reviews, I have done my best to address all comments. I also updated the official template to include TypeScript and my own example to use it.

…-docs

lmiller1990 · 2023-02-21T04:33:08Z

Will merge once 12.7 goes out with https://github.com/cypress-io/cypress/pull/25780/files in it.

astone123

Not sure if I'm looking at the wrong deployment, but I'm seeing the entire page inside of the "info" banner 🤔

astone123 · 2023-02-21T14:38:32Z

docs/guides/component-testing/third-party-definitions.mdx

+
+  // Wait until next microtick to ensure any async render logic has executed
+  return cy.wait(0, { log: false }).then(() => {
+    if (options.log) {


This won't work unless we check the value of options.log. We're assuming that it's true here but that's not the case unless it is explicitly set. Should we change this to

Suggested change

if (options.log) {

if (options.log !== false) {

astone123 · 2023-02-21T14:51:06Z

@lmiller1990 do you think we should mention dev server support at all? Maybe suggest a way to give users a custom dev server function to drop into their config until we build support for that? Is that something that we want to encourage? Not sure 🤔

lmiller1990 · 2023-02-22T01:18:45Z

@astone123

Banner CSS - what on earth, will look
options.log- will fix
custom dev server - we could add a link to our custom dev server docs, but those are kind of bad. If we could get a proper example (eg Preact) that'd be much more useful. I thought about a "caveats" section but it seems like too much information for the tiny group of developers who'd actually want to build a custom dev server. I'd love to see some better docs in general around this... We've got this but it's not exactly the most useful... :|

lmiller1990 · 2023-02-22T02:46:35Z

Banner looks good to me, tested locally - maybe preview was an old commit?

elylucas · 2023-02-22T13:01:18Z

@lmiller1990 do you think we should mention dev server support at all? Maybe suggest a way to give users a custom dev server function to drop into their config until we build support for that? Is that something that we want to encourage? Not sure 🤔

I think this is a good idea. I've been trying to throw together one and the point I got stuck on was getting the dev server up and running. One project was vite and the other is a custom dev server and couldn't really get either working. Would be good to know (and update the custom dev server section under framework configuration) how to set one up from scratch.

elylucas · 2023-02-22T13:06:37Z

Banner looks good to me, tested locally - maybe preview was an old commit?

It got messed up in a commit suggestion, I pushed a quick fix for it in #81e6b7e

wip

afd85c1

vercel bot deployed to Preview February 16, 2023 05:02 View deployment

add more info

245727e

vercel bot deployed to Preview February 17, 2023 02:35 View deployment

remove old code

07c4ade

vercel bot deployed to Preview February 17, 2023 03:48 View deployment

clarify and add anchors

809de47

vercel bot deployed to Preview February 17, 2023 03:57 View deployment

This was referenced Feb 17, 2023

SolidJS component test cypress-io/cypress#24494

Closed

feat: add lit package for component tests cypress-io/cypress#24250

Closed

feature request: Component testing for StencilJS cypress-io/cypress#24054

Open

lmiller1990 marked this pull request as ready for review February 17, 2023 04:05

lmiller1990 requested review from elylucas and a team February 17, 2023 04:05

lmiller1990 changed the title ~~CT Public API docs WIP~~ CT Public API docs Feb 17, 2023

mike-plummer requested changes Feb 17, 2023

View reviewed changes

mike-plummer requested a review from a team February 17, 2023 15:28

elylucas suggested changes Feb 17, 2023

View reviewed changes

Apply suggestions from code review

d3e3b0d

Co-authored-by: Ely Lucas <ely@meta-tek.net> Co-authored-by: Mike Plummer <mike-plummer@users.noreply.github.com>

vercel bot deployed to Preview February 20, 2023 02:49 View deployment

update

5b47f95

vercel bot deployed to Preview February 20, 2023 02:52 View deployment

update

62f251d

vercel bot deployed to Preview February 20, 2023 02:54 View deployment

update

2492794

vercel bot deployed to Preview February 20, 2023 05:10 View deployment

add testing

284dd59

vercel bot deployed to Preview February 20, 2023 05:40 View deployment

lmiller1990 commented Feb 20, 2023

View reviewed changes

lmiller1990 mentioned this pull request Feb 20, 2023

Support Public API for Third Party Component Testing Integrations cypress-io/cypress#25637

Closed

elylucas approved these changes Feb 20, 2023

View reviewed changes

mike-plummer approved these changes Feb 20, 2023

View reviewed changes

lmiller1990 added 2 commits February 21, 2023 14:18

Merge remote-tracking branch 'origin/main' into lmiller/ct-public-api…

08e9d4d

…-docs

lint

a7b75b6

vercel bot deployed to Preview February 21, 2023 04:22 View deployment

lmiller1990 mentioned this pull request Feb 21, 2023

Document CT Third Party Definitions API cypress-io/cypress#25800

Closed

astone123 reviewed Feb 21, 2023

View reviewed changes

fixing admonition issue

81e6b7e

vercel bot deployed to Preview February 22, 2023 00:36 View deployment

lmiller1990 added 2 commits February 22, 2023 12:47

lint

bc8c294

log

c20159a

vercel bot deployed to Preview February 22, 2023 02:49 View deployment

Merge branch 'main' into lmiller/ct-public-api-docs

deaa5e5

vercel bot deployed to Preview February 24, 2023 20:06 View deployment

ryanthemanuel changed the base branch from main to release-12.6.1 February 24, 2023 20:08

ryanthemanuel merged commit d09ffc8 into release-12.6.1 Feb 24, 2023

ryanthemanuel deleted the lmiller/ct-public-api-docs branch February 24, 2023 20:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CT Public API docs #5069

CT Public API docs #5069

lmiller1990 commented Feb 16, 2023 •

edited

Loading

vercel bot commented Feb 16, 2023 •

edited

Loading

mike-plummer left a comment

elylucas commented Feb 17, 2023

elylucas Feb 17, 2023

elylucas Feb 17, 2023

elylucas Feb 17, 2023

lmiller1990 Feb 20, 2023 •

edited

Loading

lmiller1990 Feb 20, 2023

lmiller1990 left a comment

lmiller1990 commented Feb 21, 2023

astone123 left a comment

astone123 Feb 21, 2023

astone123 commented Feb 21, 2023

lmiller1990 commented Feb 22, 2023

lmiller1990 commented Feb 22, 2023

elylucas commented Feb 22, 2023

elylucas commented Feb 22, 2023


		The second part of defining a Framework Definition is the Mount Adapter. This is the function that renders the component in your tests using `cy.mount()`.

		By default, Cypress will look for this as a `mount` function that is a named export from the package. This should be written in a `index.mjs` file. This example is for a [Solid.js](https://www.solidjs.com/) mount adapter:


		## Testing

		If you develop the Framework Definition file using TypeScript, for example by using [our official template](https://github.com/cypress-io/cypress-ct-definition-template), as long as you don't have any compile time errors, everything should work as expected. If you do run into unexpected behavior, please [file an issue](https://github.com/cypress-io/cypress/issues).

CT Public API docs #5069

CT Public API docs #5069

Conversation

lmiller1990 commented Feb 16, 2023 • edited Loading

vercel bot commented Feb 16, 2023 • edited Loading

mike-plummer left a comment

Choose a reason for hiding this comment

elylucas commented Feb 17, 2023

elylucas Feb 17, 2023

Choose a reason for hiding this comment

elylucas Feb 17, 2023

Choose a reason for hiding this comment

elylucas Feb 17, 2023

Choose a reason for hiding this comment

lmiller1990 Feb 20, 2023 • edited Loading

Choose a reason for hiding this comment

lmiller1990 Feb 20, 2023

Choose a reason for hiding this comment

lmiller1990 left a comment

Choose a reason for hiding this comment

lmiller1990 commented Feb 21, 2023

astone123 left a comment

Choose a reason for hiding this comment

astone123 Feb 21, 2023

Choose a reason for hiding this comment

astone123 commented Feb 21, 2023

lmiller1990 commented Feb 22, 2023

lmiller1990 commented Feb 22, 2023

elylucas commented Feb 22, 2023

elylucas commented Feb 22, 2023

lmiller1990 commented Feb 16, 2023 •

edited

Loading

vercel bot commented Feb 16, 2023 •

edited

Loading

lmiller1990 Feb 20, 2023 •

edited

Loading