New WebdriverIO Website

[christian-bromann]

Hey all 👋 ,

as we approach the end of our TypeScript rewrite effort we will publish a new major version as a lot of type definitions will change and there might be some breaking changes for TypeScript users (people who don't use TypeScript won't be affected at all). As part of the new release we plan to refurbish our docs (https://webdriver.io) to better organise information and surface all great features WebdriverIO provides. This is where you can help!

What you all think would be nice additions to the project website?
How can be better structure the content to make it easier to read and understand?
Which kind of documentation is missing?

Current items that we have planned to improve are:

• move to Docusaurus v2 (Move docs to Docosaurus v2 #5522)
• improved documentation on how stubbing and mocks work in WebdriverIO
• improved documentation which commands are supported in which environments

If you have skills in UI design and frontend work, please let us know!

[osmolyar]

It would be nice to provide more clarity about the automatic retry timeouts vs. the configured session timeout and the difference in wait behavior between $() and $$()[]

[christian-bromann]

Speaking about TypeScript, tagging #5439 here to ensure we have some docs for this.

[christian-bromann]

@osmolyar do these information help: http://v7.webdriver.io.s3-website-eu-west-1.amazonaws.com/docs/autowait ?

[christian-bromann]

Some details related to running WDIO with Docker and Kubernetes in an efficient manner would really help.

I am not sure what you mean by that. Are you talking about how to set up an internal grid in a Kubernetes cluster? If so, it feels a bit outside of the WebdriverIO responsibilities but I am happy to add such content if someone likes to write it.

To elaborate more on the second point, some before and after examples with Typescript would be very helpful

@17thSep before and after examples of what?

[christian-bromann]

Added some documentation on how to run tests in a Docker container: http://v7.webdriver.io.s3-website-eu-west-1.amazonaws.com/docs/docker

[17thSep]

For the typescript part, how would a script (i.e. Heroku example )be written in .ts when compared to the .js file. Just to give a high level view where one can use typescript over js files.

[christian-bromann]

Thanks @osmolyar and @17thSep for the feedback. Something I've seen which I like to add is a team section for the TSC team and contributors like here: https://v2.docusaurus.io/community/team as well as a resource section where we could highlight some YouTube material and blog post series.

[amrsa1]

Maybe It would be good if we have some information regarding the element strategy locators for winAppDriver

[christian-bromann]

We want to be careful to not document to many driver specific features because it should be the job of the driver to provide proper docs for this, e.g. which locator strategies it supports. Afaik it should support all the ones Webdriver.IO already defines here: https://webdriver.io/docs/selectors.html

[17thSep]

Speaking of documentation, I came up with 2 more that would be useful for me not sure about others.

1. I would love to explore the react locators instead of the traditional ones. I am currently using WDIO to automate a react application. We use custom attributes to identify elements that work well enough but would be fun to use react locators to identify react components. This could open up something new but the documentation doesn't help us to play around. this one came to my mind.

2. With the Dev tools protocol in place, we would like to use puppeteer to block any of our API's and perform the negative cases for our UI. I know cypress has it easier maybe it is the same with WDIO but one doesn't know for sure unless we read some documents. So more use cases with Devtools protocol/ Pupetter would be awesome!

[christian-bromann]

I would love to explore the react locators instead of the traditional ones.

@17thSep can you elaborate what you are missing specifically? I know we have some documentation on the command but I wonder what we could add to make this more clear.

So more use cases with Devtools protocol/ Pupetter would be awesome!

We actually have this use case already documented

[17thSep]

The bit that's unclear maybe only to me is will this react selector be an alternative to the css/xpath etc.. or the only way to select those elements.
Let's say for a person who has no idea about why do we have to go react selectors instead of the usual route would be really helpful. I am thinking of a reference to a Heroku internet page with some examples.
I will anyways want to create a video on it though :P

[klamping]

Here are a couple things I'd like to see improved on the new site:

Better site search results

The search results currently aren't "weighted". For example, take searching for 'click'

Notice how the most important result, the element 'click' action, is hidden below the window. This could lead newcomers to using less ideal solutions (e.g. elementClick instead of click).

A "simple" solution would be to weight 'browser' and 'element' results above everything else, since those are what's most likely to be used. Honestly that's probably enough to fix the majority of issues around this.

View site by version, including showing current version in the header

There is some versioning of the site available, but it would be really nice to have a way of seeing what version of the docs you're looking at in the header, and switch versions as well. For example, on the https://vuejs.org/v2/api/ site, they have that functionality in the top left.

[christian-bromann]

Better site search results

I am sure Algolia supports this and hope it is just a matter of configuration.

View site by version, including showing current version in the header

This might be very difficult as we auto-generate the docs and it would require a lot of effort to configure the build script to clone the old versions and generate the docs from there. The easiest solution I could see is that we improve the doc setup for previous versions and show a banner in there and re-upload them.

[klamping]

For the versions, the main thing is for the major versions to be noted. With the API changes between v5 and v6, there were some times early on that it was confusing what the right command was for the right version. Just being able to easily see, "Oh, I'm on v5" or "Oh, these are v6 docs, I need v5" would have been great. Not as big of a deal with the v6-v7 conversion, but still nice to have.

[christian-bromann]

I made it so it displays the current major version at the top of the page:

We can now go back in previous versions - re-build the page to display that version there too and re-upload.

[christian-bromann]

Hey you all,

you can preview the current state of the new docs here: http://v7.webdriver.io.s3-website-eu-west-1.amazonaws.com/. We are working with a couple of designers to improve the setup and look of the start page (so ignore this page for now 😉 ).

Please keep posting feedback and let me know what you think of them. Thanks!

[MikoSh95]

Also http://v7.webdriver.io.s3-website-eu-west-1.amazonaws.com/community/support loads forever/doesn't work at all

[christian-bromann]

fixed

[MikoSh95]

And moving on to more specific problems: in http://v7.webdriver.io.s3-website-eu-west-1.amazonaws.com/docs/options#protocol this option seems to be kind of a dictionary, but the possible values are not listed. I guess there are only 'http' and 'https' possible values but maybe it should be written explicitly?

[MikoSh95]

I've noticed that using "Edit page" button leads to 404 Github page. Can it be fixed for this "beta" version?

[christian-bromann]

@MikoSh95 good point, fixed it! Any wording PRs or any other contributions are appreciated 😉

[erwinheitzman]

Guides

I'd love to see our guides be expanded with things like:
Appium
Docker
Continuous integration

---

Best practices

I'd love to see a best practices section where we list best practices (created by the TSC / committers) and explain the reasoning behind them.

---

Simplification

I'd love the documentation to be simplified and updated using modern javascript examples.

For example, just showing a async/await example instead of also a then example should suffice imo.

Examples in the Getting Started like npx wdio run wdio.conf.js might be simplified to npx wdio for short and instead of explaining what options can be passed to the CLI/wdio I'd keep it to a single example and add a reference/link to all the available options described in the CLI/wdio documentation.

---

Features

I'd love to see our best features to be mentioned in the front page. Things like easy (cross browser?) stubbing/mocking might be a nice selling point.

---

Lastly I want to add that I completely agree with what @klamping had to say 👍

[christian-bromann]

@erwinheitzman thanks for the feedback, some comments:

I'd love to see our guides be expanded with things like: Appium, Docker, Continuous integration

We already have documentation on Jenkins and Bamboo integrations. Is there anything you like to see in particular? Same for Appium - I am not sure how much we should document how to set it up since this is "Appiums job" to document. Maybe @wswebcreation can provide some feedback here as well?

For example, just showing a async/await example instead of also a then example should suffice imo.

There are not many occurrences of suche examples, can you point me to them? Same for npx wdio run, there is only one occurrence.

[erwinheitzman]

@christian-bromann

I would love to see examples of integrations with Github Actions, Bitbucket pipelines, Circle CI, Travis CI, AWS Amplify (also AWS lambda's) and Docker.

Why is it Appium's job to document WebdriverIO? Why not take the responsibility for ourselves?

It is true that it's only mentioned once, but it is mentioned in the most important place.. the Getting Started. Which Is why I feel this is important because you want to give people the feeling that the tool is really easy to use without showing all the possible ways you can/could run the application. Things like the async/await example I feel are important because you want to show people the best way to use the tool, and that is async/await and not somePromise.then(() => ...). I just don't see a reason as to why we would explain what a promise is and the different ways you can use promises. Just showing the most up to date code example should suffice in showing the user how it works, else you are documenting Javascript and not WebdriverIO.

[christian-bromann]

Why not take the responsibility for ourselves?

It's like @17thSep comment above. Sure it would be nice to have a tutorial for how to set up an Appium in-house grid on AWS using X and Y. However this doesn't have much to do with WebdriverIO anymore as it doesn't care about the environment where the tests are being run. That said, I don't mind if someone has made experiences setting this up and wants to share it. Note that having that kind of "external" documentation also requires maintenance as they it can go out of date. Since you can integrate WebdriverIO with almost everything this can become easily out of hand.

[christian-bromann]

Added some documentation on how to run tests in a Docker container: http://v7.webdriver.io.s3-website-eu-west-1.amazonaws.com/docs/docker

[MikoSh95]

@christian-bromann Edit link for this page doesn't work. It would be nice to add '--disable-dev-shm-usage' to Chrome capabilities since lack of it often causes Chrome crash on startup.

More about this problem here: https://developers.google.com/web/tools/puppeteer/troubleshooting#running_puppeteer_in_docker

[khanzzirfan]

I'm a frontend dev and we build storyboook react components and also build some SPA. Below are few things I faced when setting up webdriver io

• Setup path screenshots (visual comaprison) for each packages inside monorepo. (have to write custom hook to keep tack of the path)
• Appending screenshots filenames with <browser_version_os> for comaprison
• Selenium Standalone downloadable path inside config and then Webdriver version to use. This is when behind the proxy (corportate)
• Visual comparison comparescreenshot has some issues with innerwidth/ outwidth of the viewport. Have to make custom changes on it.
• setting up Mockservice per each test differently. That needs to be documented. Also Intercepting the request based on /regex/ and then return the mock results.
• Explain better $ and $$() usecase
• Document Inject Authorization headers use case in better way in localstorage or cookie sessions.
• Cleanup cookies as and when required.
• After hooks to generate allure report or send them to Allure Server documentation required.
• Report Portal Plugin to actively feed resutls directly to Report Portal server. Including Image snapshots
• Running test cases based on filters/ attributes / Tags from command line. Sometimes its better to execute via command line than having in config.

[khanzzirfan]

UI wise, Its looking good already. But I would sugges to have a comments or Page edits on github. for continues improvements. and feedbacks

[christian-bromann]

Thanks everyone for the feedback. Hope you all like the new project docs. Closing this one.