added experimental typescript support

[nuclearglow]

Closes #209

• updated docs
• exposed typings through package.json
• Bonus: added package.json schema

This solution would mean that everyone using Taiko with TypeScript would be exposed to the Typings provided, but there is also an optional solution which would make the typings optional but requires a bit of configuration work for every project using it:

• the types folder in the repo would contain a taiko folder with a index.d.ts
• the typings could be consumed using the "types" field in tsconfig.json
• a user with gauge-ts setup would have to edit tsconfig.json in this way:

{
    "compilerOptions": {
        "typeRoots": ["node_modules/@types", "node_modules/taiko/types"],  // add available taiko TypeScript Type Definition folder to the project
        "types": ["node", "taiko"] // use taiko types in the project
    }
}

If you prefer to keep this optional, let me know and I will update the PR.
Possible TODOs:

• The typings themselves are workable, but likely need more work to reflect the current API better.
• The API reflected is 1.0.2, I did not include any changes from there to the current version

Hopefully, we can work together to include typings for Taiko :-)

[nuclearglow]

Here is an example repo I just created using this PR branch for a Gauge TS Taiko example:
https://github.com/nuclearglow/gauge-ts-taiko-types-example

need to discuss reflect mechanism

[sriv]

@nuclearglow - what do you suggest is the best way to keep the types in sync? Is there any automated mechanism that you know of, which can be hooked up t0 husky?

Do you think it makes sense to port some tests to TS and make them run in the pipeline?

thanks for the contribution!

PS - i had approved this PR, but then I figured we should discuss these...

[nuclearglow]

@sriv yes, I had a look at available tools that produce typings automatically, but my preliminary assessment is that they do not really work with the Taiko API, as it is really flexible and allows a lot in the method parameters, all of this is pretty hard to configure out automatically. So I would recommend that extensive testing of the typings should be implemented. It would certainly mean that a TypeScript project needs to test the Taiko API methods using the available parameters and should check whether the project still compiles. This way, any future changes to the API which breaks the typings would mean that TypeScript tests are failing - and then the typings could be enhanced to reflect the newest API changes. Of course, new methods would need new tests and possibly new typings.

[nuclearglow]

I would also recommend that Taiko declares TypeScript support as experimental for the next releases until we work these things out and would therefore only allow projects to set up the typings manually, this way we can get some feedback from real world projects out there if the typings work against their test projects - and at the same time we do not break existing TypeScript test projects where the typings are inadequate.

If you think that is the way to go, I will update this PR so that the README, the folder structure and the setup only supports manually configured projects, just let me know.

[nuclearglow]

The most important thing we should discuss within the Typings themselves is the TaikoSearchElement (https://github.com/getgauge/taiko/pull/1125/files#diff-6d9454e03789edeaeb913b3ff375045fR64), as you can see this basically allows everything and it shows a weak point in my typings. But I do not know enough about how the Taiko API works internally to provide stronger typings or a better interface...

[sriv]

So I would recommend that extensive testing of the typings should be implemented.

Agreed.

I would also recommend that Taiko declares TypeScript support as experimental for the next releases until we work these things out

Fair enough. We usually toggle experimental features off, but manual config to enable it works equally well.

On the types -

• is there a reason to have Taiko prefixed on most (all) types? Would it be possible to use namespaces instead?

Regarding TaikoSearchElement - in taiko, the input to any element search can be either -

• string
• instance of elementwrapper
• instance of element

As a result you'll see checks like this: https://github.com/getgauge/taiko/blob/master/lib/taiko.js#L1151

it'd be nice to have types, but we are just touching the interface here. I think it'd be good to constrain TaikoSeachElement to just these. Thoughts?

[nuclearglow]

Hi @sriv thanks for your feedback, I have worked on the PR and made some updates:

• experimental TypeScript support now needs to be configured manually in the gauge-ts project's tsconfig.json, I have updated the README with an example. Also see my updated example repo which is configured to work with the PR branch -> https://github.com/nuclearglow/gauge-ts-taiko-types-example
• the taiko/index.d.ts already declare a module taiko, so I have removed the Taiko prefix everywhere, should work fine, if there are name clashes, usually VS Code or IntelliJ allows to choose from the module, which would then be taiko for us. An import in StepImplementation.ts would look like this: import { BrowserOptions } from 'taiko';
• I have not changed the TaikoSearchElement right now. I have taken a deeper look at this and I want to discuss an example from your API: https://docs.taiko.dev/#click. Here, it is possible to provide a string, a selector and an Object, such as {x: int, y: int}. I have not typed this, instead I allow generic objects. Either we provide interfaces to deal with Objects in the taiko API or we use the generic option. I would like the former, but I do not know how much work that would be. What do you think? Should we implement specific interfaces for the Object parameters? I might need help to catch them all...

[sriv]

👍 on (1) and (2).

Regarding TaikoSearchElement: I too like the first option of having interfaces rather than generics.

string is straightforward. For selector and Object, taiko looks for Object to map to an Element. Since JS does not make type safety easy, we added a helper method IsSelector and IsElement.

Does this help? Perhaps we can start porting some of our tests to use the TS bindings?

[nuclearglow]

Hey @sriv thanks for the pointers to the helper methods, I managed to learn a bit more. I think we can restrict the SearchElement type to the types you mentioned, but I will need to go through the API and be on the lookout for special cases. I found this in taiko.js:1300:

 if (isSelector(selector) || isString(selector) || isElement(selector)) {
...
  } else {
    options = setClickOptions(options, selector.x, selector.y);

This basically means that there are special cases for the selector which are going further than selector, string and element types. So I propose that we restrict the SearchElement to the instances you mentioned, I will analyse the helper methods to see that I catch everything you check. And for special parameters like in click() where a coordinate can be given as a SearchElement, I would then type something like this:

selector: SearchElement | MouseCoordinates

And yes, we could start porting some test cases to use TypeScript, can you help with the initial setup and maybe provide an example if you know to to go about this, then I could help with some tests as far as my project budget allows. If we should think about how to do it, let me know, I will help.

[nuclearglow]

OK, a new update with some updated typings after I have taken a look at the helper functions and the API again. Basically, I have upgraded the basic SerachElement definition to allow only the stuff that Taiko would accept:

    // BasicSelector mimics isSelector
    export interface BasicSelector {
        // FIXME: @sriv: is that correct?
        elements: Element[] | Node[] | string[];
        exists(): boolean;
        [key: string]: any;
    };
    // isSelector also allows ElementWrapper instances
    export type Selector = BasicSelector | ElementWrapper;
    // SearchElement mimics isSelector, isString, isElement
    export type SearchElement = string | Selector | Element;

[sriv]

Sounds like good progress @nuclearglow ! I will take a closer look soon (feel free to ping me here if I am blocking your work), in the meantime there are some merge conflicts :)

[gaugebot]

@nuclearglow Thank you for contributing to taiko. Your pull request has been labeled as a release candidate 🎉🎉.

Merging this PR will trigger a release.

Please bump up the version as part of this PR.

Instructions to bump the version can found at CONTRIBUTING.md

If the CONTRIBUTING.md file does not exist or does not include instructions about bumping up the version, please looks previous commits in git history to see what changes need to be done.

[NivedhaSenthil]

args is a rest parameter and its type has to be RelativeSearchElement

[nuclearglow]

changed

[NivedhaSenthil]

args is a rest parameter and its type has to be RelativeSearchElement

[nuclearglow]

changed

[nuclearglow]

Hi @NivedhaSenthil thank you for the great feedback, I have tried to add everything as far as I understood it. I still have some trouble with the relative searches, they are hard to type since it is a bunch of methods... But I superficially typed the RelativeSearchElement and added it as the return type of the proximity methods, I hope this will work out. At this point, I would need real TS tests to check that everything can be typed as we envision it. I will try to add some to my gauge TS example project soon. Please review my changes and let me know if you have more feedback!

[NivedhaSenthil]

PR looks fine for an initial TS support, this is a great effort :) Will try adding some test in TS and port some existing test also.. Do follow #1152 for any progress.

[ghost]

Hi there. If I understand this thread correctly then the experimental Typescript is only available if Taiko is used in conjunction with Gauge. Is this correct? If not, could someone maybe explain (to a non-expert) how Typescript could be used for writing test cases if other test frameworks (e.g. Jest, Mocha) are used?

[zabil]

Typescript is only available if Taiko is used in conjunction with Gauge.

The typescript bindings are for Taiko. You can use these binding with any test runner. You can refer https://docs.taiko.dev/experimental_features/#typescript-support on adding configuration to tsconfig.json

[ghost]

@zabil Great, that has clarified it, thanks a lot!