Jest: Add playground to website

[kvendrik]

🚀 Feature Proposal

@orta and myself have been discussing adding a playground to the Jest website using an approach simular to what Jest Lite uses. I'm opening this issue as I'd like to get the team's thoughts on this (I have a feeling it has come up before 😄).

Motivation

On the homepage we show a lot of output examples. A playground could show people how all these things work in practise and let them play around with it. Once we have that in place we could even use it as a form of documentation by providing SEO-friendly examples.

Example

TypeScript's playground would be a good example I think. @orta also did some rough mockups for a Jest cookbook which is close to what we'd have in mind for this (simple editor + output).

Pitch

I think @orta gave a pretty good explanation of the value this would add here:

The JS reference for Jest covers what all the pieces are, but doesn't necessarily cover how they come together

Also see the motivation section above.

cc @SimenB tagging you on this as well considering you already have some context on Jest Lite 😄

[SimenB]

@orta talked about this when we met up in March, and I think it's mostly in his head beyond the sketches he shared with you. I don't _think_ we have any other issue for this. But we are most definitely keen on getting something like this running. I suggested just embedding codesandboxes, but having it run natively would be super cool, especially for debugging.

/cc @cpojer @rickhanlonii

[cpojer]

What's wrong with repl.it?

[SimenB]

nothing wrong with it, and I guess we could use it instead of code sandbox. This issue is about a version of jest running natively in the browser, though, and writing examples etc with that

[cpojer]

I would prefer a full version of Jest over a simplified one that doesn't have the full feature set.

[kvendrik]

@cpojer yeah I agree, the usage should be the exact same as when you would install Jest yourself. What are your general thoughts on having a playground with examples? Anything apart from what @SimenB already mentioned?

[cpojer]

I think that's a great idea but since Jest itself doesn't run in browsers the only way to run a full version of Jest is by running it in a remote VM, like repl.it is doing.

[kvendrik]

@cpojer Yeah think it would have to be a setup where we have something like repl.it embedded as the code editor. Embedding repl.it seems to work pretty well, I think even just simply embedding that onto a page with some common examples could be pretty great. From a UX standpoint I'm a little concerned about the noise in Repl.it's UI, feel like it might make the example harder to understand but we can explore it and see how far we get.

[orta]

Yeah, I would love to use repl.it - it'd take quite a bit of UI work in repl.it to have it make sense when embedded inside the jest website as a playground though, and that's a bit out of our control

Jest lite is working, covers most cases (I assume jest.mock isn't covered?) and the design/features can be fully controlled by the site

[kvendrik]

@orta yeah agreed, I do agree with @cpojer though that we don't want to give users the wrong impression in a case where they, say, try customizing the example and its missing features.

Having that said, Repl.it's UI could be a bit of an issue as there seems to be a good amount of clutter when embedded. I quickly embedded Repl.it onto a new playground page and this is what I got. How do we feel about this?

[orta]

I think it's a step forwards 👍 - perhaps a sidebar that links to different repl.it examples?

[kvendrik]

Yeah I feel it might be okay in terms of clutter. As a next step I'll add a way to explore different examples.

[kvendrik]

Okay so this is going pretty okay but hitting some roadblocks:

1. In the Jest Repl.it environment the config.json file is the first file and as I don't have control over what file Repl.it shows first when embedded every example starts with the config which isn't great. Any way we could change that @SimenB?

2. Second this is that the website seems to strictly SSR React which means event handlers don't seem to work. Does anyone know if there's an easy way to get that to work?

[SimenB]

1. I don't know. Maybe @amasad could help us? It'd be great to upgrade to Jest 24 as well
2. Docusaurus 2 should support client side scripts, so we can wait for that to be more feature complete. https://v2.docusaurus.io/

[bnb]

As someone who is working on learning testing with Jest, wanted to share some feedback on what's already been commented:

I would prefer a full version of Jest over a simplified one that doesn't have the full feature set.

100% agree. Having everything allows me to look at projects that already use Jest and try to emulate the APIs they're using in addition to picking and choosing from the docs.

In the Jest Repl.it environment the config.json file is the first file and as I don't have control over what file Repl.it shows first when embedded every example starts with the config which isn't great. Any way we could change that @SimenB?

I know that Glitch provides a lot of control over what you can/can't see. I don't want to throw a wrench in this, but it may be an alternative worth considering. I'm sure they'd also be more than willing to help out – they've been very helpful with nodejs.dev so far!

Additionally, I wanted to give some feedback in general on what would be helpful for my experience so far:

• getting clarity / examples on how to level-up from most basic example to more complex use cases
• teaching things outside of just code – file setup, directory structure, etc. and how developers can approach that effectively
• showing how to configure jest effectively

[amasad]

Hey! Repl.it founder here, happy to help.

So the issues are:

• Upgrade to v24
• Customize entry point
• Anything else?

@kvendrik re the following, I'm curious what's the clutter in embedded mode? It's only header, editor, and console. What could be better?

Having that said, Repl.it's UI could be a bit of an issue as there seems to be a good amount of clutter when embedded. I quickly embedded Repl.it onto a new playground page and this is what I got.

[mattphillips]

Thanks @amasad!

Anything else?

I think being able to install dependencies into the Jest repl is pretty crucial and being able to configure the Jest config.

As an example I'd love to write a repl for jest-extended docs. To do that we'd need to install jest-extended and configure Jest to use jest-extended in the setupFilesAfterEnv option.

[orta]

it would also be great to have the definitely typed jest type definitions available inside the editor, then you get auto-complete and inline docs 👍 ( it'd look something like this )

[kvendrik]

Hey @amasad!

To break it down:

Must-have

• Upgrade to Jest v24.
• Being able to customize the entry point so users don't have to navigate files to see the example.

Nice-to-have

• A way to hide everything except for the editor + output + run button would be nice for a more focussed view.
• I'm also thinking it might be nice to auto-run examples or show a cached result initially so people don't have to press "run" first to get an idea of what will happen.

Then, there's also, as @orta said, the ability to use types in the editor which is probably a nice-to-have.

What @mattphillips said seem to already be possible (by opening a shell and manually installing the module) so think we're good there? @mattphillips would you be able to confirm?

[amasad]

Hey guys, sorry for the delay, I was waiting for some infrastructure upgrade to make this smoother. In the next couple of days, I'll be deploying a new version of the latest Jest and on top of that it will have:

• packager support
• LSP (autocomplete and Jest docs inline)
• Overall more stable and configurable

I'll get the new version up tomorrow or the day after.

[amasad]

hey @kvendrik/everyone. The version has been updated and now and the file to be rendered first can be selected using the fileName query param like so: https://repl.it/@amasad/test-jest-file?fileName=add.js

I'll let you know when the rest of the stuff I mentioned above has been deployed.

[amasad]

Hey everyone (hope y'all having a great holiday season)!

Not sure if you saw our announcement about our GitHub integration. A great side-effect is that the Repl.it environment became now much more configurable. You don't have to rely on us to create and maintain the image for you and you have a lot more flexibility in how to run and structure the code.

I went ahead and created a new playground for jest:

• repl: https://repl.it/@amasad/jest-playground
• repo: https://github.com/amasad/jest-playground

You can have your users fork it for reproducing issues or what have you. As an example, here is a fork of that that configures Babel: https://repl.it/@amasad/jest-playground-babel

The only downside to this approach is the initial install time when loading up the repl. However, we have a solution for this coming very soon. A blazing fast dependency caching solution.

I'd love to hear your feedback because I'd like to deprecate repl.it/languages/jest and redirect people to what I laid out above.

[rickhanlonii]

Wow @amasad that's a great update thanks!

[amasad]

@rickhanlonii thoughts on updating the issue template with it? It's probably best if you or whoever is going to maintain it fork it on your repl.it account.

[rickhanlonii]

Here's the setup I'd propose:

• Create a @jest repl.it account
• Share credentials with the core team
• Create a @jest/latest playground
• Create a @jest/version for the last few version
• Update template to link to latest and explain the other versions

How does that sound @amasad @thymikee @SimenB @orta

[amasad]

That sounds good. The Rollup team is doing something similar. cc @shellscape https://github.com/rollup/plugins/commit/3380920d7ed7cafafe442bb79f1d1c3559280380

[shellscape]

Yes we've added a "reproduction" repl.it for users to provide repros on rollup plugin issues. The main Rollup REPL is great for core repros, but not for plugins. We're hoping this cuts down on code pasting in issues, and triage time for maintainers.

[amasad]

Hey hey! I went ahead and created a @jest repl.it account and in it the base template y'all can use for this. Try it out: https://repl.it/@jest/jest-playground

You'll notice that:

• it's faster (even dependencies are cached)
• more customizable
• and easier to maintain; updating jest is as easy as bumping the version in package.json

@rickhanlonii @SimenB @thymikee Can one of you email me and I can give you access to the account? [email protected]