docs(testing): adding WebdriverIO docs

[christian-bromann]

This patch adds docs on top of the docs-reorg PR for WebdriverIO Testing.

In the docs you will see that I am trying to get some basic docs in place but mostly reference to the WebdriverIO project docs.

[vercel]

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

Name	Status	Preview	Comments	Updated (UTC)
stencil-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 13, 2024 1:01am

[rwaskiewicz]

Adding the rest of the team here - I encourage everyone to run through these instructions on your machine. Please play with the docs + examples here as if you were an end user attempting to use WebdriverIO and use that to drive feedback

[alicewriteswrongs]

some questions and comments!

[alicewriteswrongs]

Suggested change

	- __Web Platform Support__: Running tests in actual browser allows you to tap into the latest Web Platform features for testing your components, often not available when using virtual DOM environments.
	- __Web Platform Support__: Running tests in actual browsers allows you to tap into the latest Web Platform features for testing your components, often not available when using virtual DOM environments.

should we maybe highlight that this keeps polyfills out of the picture, i.e. if you test an integration with a given DOM API you're testing the integration with an actual browser engine and not the integration with however it's implemented in JSDom (which could be anything from quite close to standards-compliant to way, way off)

[christian-bromann]

add a 4th point>

• Real Environments: Run your tests in an environment that your users are using and not somewhere that re-implements web standards with polyfills like JSDOM.

[alicewriteswrongs]

this is fun haha

[alicewriteswrongs]

I was able to stand up a new project easily with npm init wdio@latest and so on and faced no issues, however when I tried to add webdriverio stuff to an existing project I faced a bit of an issue.

I first created a new test stencil project like so:

mkdir /tmp/test && cd /tmp/test
npm init stencil component test-adding-wdio

then after doing an npm install and whatnot I ran:

npm init wdio@latest .

this ran through the wizard with no problems, and it looks like it cleanly installed things over my existing setup, but then when I try npm run wdio I get:

I then went to install ts-node and then get a different error:

I have no idea what I'm doing with wdio so probably missing something! But j/w two things:

• is adding wdio tests to an existing project using the init starter something that's supported?
• if so, is that something we should document here?

I imagine there's going to be some interest in using this approach for the e2e tests in existing projects, so we might want to make sure that's documented.

[christian-bromann]

Two errors happened here which are bad DX and a bug in WebdriverIO:

• first, currently WebdriverIO assumes ts-node to be installed for all TypeScript projects, this assumption is wrong though. I raised an issue in the WebdriverIO project and can tackle this quickly.
• second, the config is written in ESM while a new Stencil project is set up as CJS project - it is currently very difficult to find out what environment the project is set up with but this is DX I can also fix on the WebdriverIO side - in the meantime, let me add a comment to rename the config to .mts

[rwaskiewicz]

I ran into this as well - would renaming the config extension to .mts work? I tried that locally and ran into issues there:

ERROR @wdio/config:ConfigParser: Failed loading configuration file: file:///private/tmp/wdio-basic-test/wdio.conf.ts: Cannot find module '/private/tmp/wdio-basic-test/wdio.conf.ts' imported from /private/tmp/wdio-basic-test/node_modules/@wdio/config/build/node/RequireLibrary.js
Error: Cannot find module '/private/tmp/wdio-basic-test/wdio.conf.ts' imported from /private/tmp/wdio-basic-test/node_modules/@wdio/config/build/node/RequireLibrary.js
    at finalizeResolution (/private/tmp/wdio-basic-test/node_modules/ts-node/dist-raw/node-internal-modules-esm-resolve.js:366:11)
    at moduleResolve (/private/tmp/wdio-basic-test/node_modules/ts-node/dist-raw/node-internal-modules-esm-resolve.js:801:10)
    at Object.defaultResolve (/private/tmp/wdio-basic-test/node_modules/ts-node/dist-raw/node-internal-modules-esm-resolve.js:912:11)
    at /private/tmp/wdio-basic-test/node_modules/ts-node/src/esm.ts:218:35
    at entrypointFallback (/private/tmp/wdio-basic-test/node_modules/ts-node/src/esm.ts:168:34)
    at /private/tmp/wdio-basic-test/node_modules/ts-node/src/esm.ts:217:14
    at addShortCircuitFlag (/private/tmp/wdio-basic-test/node_modules/ts-node/src/esm.ts:409:21)
    at resolve (/private/tmp/wdio-basic-test/node_modules/ts-node/src/esm.ts:197:12)
    at nextResolve (node:internal/modules/esm/hooks:865:28)
    at Hooks.resolve (node:internal/modules/esm/hooks:303:30)

Wouldn't the config file need to be a CJS module? Or am I misunderstanding the issue here?

[christian-bromann]

@rwaskiewicz I think you missed to update the wdio script in the package.json which still points to a wdio.conf.ts file. I tested it and changing to .mts works. The problem is that the Stencil starter project is a CJS project unless you do either of the two changes:

• rename wdio.conf.ts to wdio.conf.mts (my preferred choice)
• add "type": "module" to package.json (related to work proposed in STENCIL-1051)

The other option is to have WebdriverIO compose the whole thing as CJS (use require instead import) but that sounds like a step backwards to me.

I will add an admonition telling users to make this change, and check the ESM state of their project as I think this is the easiest way to unblock this.

[christian-bromann]

I added the following two admonitions:

The example component generated by WebdriverIO uses fragments which causes TypeScript to fail due to missing jsxFragmentFactory settings. I left this out as it seems straightforward how to fix it and chances are that users either don't generate them or remove them immediately. Let me know if I should add an admonition for this too.

[tanner-reits]

Content looks good! Just some grammatical stuff and marked a few spots to use npm2yarn

[tanner-reits]

Ooh nice, we'll wanna recommend this in Playwright too. Sean said Framework has a lint rule, but idk if they used a published rule or rolled their own.

[rwaskiewicz]

Nice! I had a few comments/asks, most of which are minor little nitpicks.

One more general ask - it's not clear to me from the documentation how well WebdriverIO (or any other testing framework) would integrate with npx stencil test out of the box. Can we add a blurb somewhere that explains/answers:

• "Should I continue using npx stencil test?"
• "How do existing tests integrate with my existing Stencil setup?"