From 339789039dbc13f7c5762a8ee5dea16219a0597b Mon Sep 17 00:00:00 2001 From: Hung Viet Nguyen Date: Sun, 24 Apr 2022 01:50:24 +0700 Subject: [PATCH 1/8] feat: Add CONTRIBUTING.md [skip ci] --- CONTRIBUTING.md | 80 +++++++++++++++++++++++++++++++++++++-- HOW_JEST_PREVIEW_WORKS.md | 31 +++++++++++++++ README.md | 29 +------------- 3 files changed, 110 insertions(+), 30 deletions(-) create mode 100644 HOW_JEST_PREVIEW_WORKS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65efcd57..a265f8f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,79 @@ -# Contribution +# Contribute to Jest Preview -We are working on writing a contribution guideline. Progress track at [Missing CONTRIBUTING.md](https://github.com/nvh95/jest-preview/issues/26) +## Welcome -For now, please see [Run Jest Preview Locally](./README.md#run-jest-preview-locally). Stay tune for a more details `CONTRIBUTING.md` file. Thanks. +TODO: Welcome and appreciate contributors. Jest Preview is a community-driven project. + +## What can I contribute? + +- Docs +- Fix bugs +- Add new features +- Answer questions and issues on GitHub and Discord + +## Claim issue + +- See docusaurus's docs: https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#claiming-issues + +## Run jest-preview locally (Quick start) + +- npm install +- npm run build:watch +- npm run types (optional to emit types, need to run only once) +- npm run server (to start Jest Preview Server) +- npm run test:only (to run Jest tests at `/demo`) + +## How jest-preview works + +- See [HOW_JEST_PREVIEW_WORKS.md](./HOW_JEST_PREVIEW_WORKS.md) + +## Repository architecture + +- not use monorepo (yet) +- src +- server +- demo +- config/jest +- dist: build +- examples +- website + TODO: Add absolute link to each folder. + +## Submit a PR + +- Make sure CI passes +- prefer atomic commit +- prefer rebase (avoid merge commits) + +## Closing + +TODO: To remove `Run jest-preview locally` from README.md + +draft + +Install dependencies + +```bash +npm install +``` + +To see the real demo app + +```bash +npm run dev +``` + +Run `jest` and ` jest-preview` simultaneously + +```bash +npm run test +``` + +Open chrome at http://localhost:3336 to see the preview + +However, it's recommend to run `jest` and `jest-preview` separately + +```bash +npm run server # Run jest-preview server +npm run test:only # Run jest +``` diff --git a/HOW_JEST_PREVIEW_WORKS.md b/HOW_JEST_PREVIEW_WORKS.md new file mode 100644 index 00000000..e5a8a336 --- /dev/null +++ b/HOW_JEST_PREVIEW_WORKS.md @@ -0,0 +1,31 @@ +# How Jest Preview Works + +## Components + +- Jest Preview Server +- External Browser +- Jest process + +## How Jest Preview's components interact + + + +- Jest process snapshots the app, save html file to `node_modules/.cache/jest-preview`. +- Jest Preview Server serve the html file to the browser. +- If html file changes, Jest Preview Server will send a websocket event to browser to trigger reloading. + +## How to display images and CSS + +### Images and CSS imported to components + +- [Code transformation](https://jestjs.io/docs/code-transformation) +- File transformation: Serve source file directly +- CSS transformation: + - CSS Modules + - styled-components + - Sass + - Vanilla CSS + +### Global images and CSS + +- Via `jestPreviewConfigure`. diff --git a/README.md b/README.md index 21eb8400..02b32d35 100644 --- a/README.md +++ b/README.md @@ -99,34 +99,9 @@ Jest Preview comes with [Pre-configured transformation](https://www.jest-preview - Multiple preview. - [You name it](https://github.com/nvh95/jest-preview/labels/feature_request). -## Run jest-preview locally +## Contributing -Install dependencies - -```bash -npm install -``` - -To see the real demo app - -```bash -npm run dev -``` - -Run `jest` and ` jest-preview` simultaneously - -```bash -npm run test -``` - -Open chrome at http://localhost:3336 to see the preview - -However, it's recommend to run `jest` and `jest-preview` separately - -```bash -npm run server # Run jest-preview server -npm run test:only # Run jest -``` +We can't wait to see your contributions. See more at [CONTRIBUTING.md](/CONTRIBUTING.md) ## Contributors ✨ From b148f3e7a5f90c55fbb4b82f27dffda2046236f9 Mon Sep 17 00:00:00 2001 From: Hung Viet Nguyen Date: Fri, 6 May 2022 18:38:26 +0700 Subject: [PATCH 2/8] feat: updating CONTRIBUTING.md --- CONTRIBUTING.md | 12 ++++++++++-- README.md | 2 +- website/docs/others/contributing.md | 4 +++- 3 files changed, 14 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a265f8f2..fb36c4c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,15 +2,23 @@ ## Welcome -TODO: Welcome and appreciate contributors. Jest Preview is a community-driven project. +Welcome to CONTRIBUTING zone. If you are reading this, you are probably want to contribute to Open Source projects. That's great! Contributing to an open source project is a great opportunity to learn, sharpen your skills and help others. Luckily, Jest Preview is a free and open source project and we always wecome new contributors. Its mission is to help front end developers' life easier and more enjoyable, also improve the standard of front end applications by encourgaging them to write more high-quality tests, by providng an ability to view the actual UI in Jest in an external browser like Chrome. + +Jest Preview aims to be a community-driven project. So we hope to see your contributions to make Jest Preview a favourite library for front end developers when it comes to testing. ## What can I contribute? -- Docs +We appreciated any helps. There are not a thing as small contribution. If you see a typo, send us a PR. If you experience a bug, please open an issue. If you have a suggestion, let us know. Bellow are some ways to contribute to Jest Preview: + +- **Submit bugs or issues:**: Software are full of bugs. If you use Jest Preview and find a bug, please open an issue at [Jest Preview's issues](https://github.com/nvh95/jest-preview/issues) +- **Docs**: We have a documentation site at [www.jest-preview.com](https://www.jest-preview.com/docs/getting-started/intro), (draft) it's very easier to contribute to the documentation by using `Edit this page` feature (insert image) - Fix bugs - Add new features +- Grammar: not native English speakers. - Answer questions and issues on GitHub and Discord +If not sure what to contribute, Join Discord + ## Claim issue - See docusaurus's docs: https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#claiming-issues diff --git a/README.md b/README.md index 02b32d35..57ec738f 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,7 @@ Jest Preview comes with [Pre-configured transformation](https://www.jest-preview ## Contributing -We can't wait to see your contributions. See more at [CONTRIBUTING.md](/CONTRIBUTING.md) +We can't wait to see your contributions. See the Contribution Guide at [CONTRIBUTING.md](/CONTRIBUTING.md) ## Contributors ✨ diff --git a/website/docs/others/contributing.md b/website/docs/others/contributing.md index 89834d77..5b022132 100644 --- a/website/docs/others/contributing.md +++ b/website/docs/others/contributing.md @@ -4,4 +4,6 @@ sidebar_position: 2 # Contributing -TBD +See Contributing guidelines at [CONTRIBUTING.md](https://github.com/nvh95/jest-preview/blob/main/CONTRIBUTING.md) + + From 97d18ff02a9c5c0e453e90c67142a7a20fc02751 Mon Sep 17 00:00:00 2001 From: Hung Viet Nguyen Date: Tue, 10 May 2022 11:39:13 +0700 Subject: [PATCH 3/8] feat: Update CONTRIBUTING.md --- CONTRIBUTING.md | 104 +++++++++++++++++++++++++++--------------------- 1 file changed, 58 insertions(+), 46 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb36c4c4..b5414433 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,76 +2,56 @@ ## Welcome -Welcome to CONTRIBUTING zone. If you are reading this, you are probably want to contribute to Open Source projects. That's great! Contributing to an open source project is a great opportunity to learn, sharpen your skills and help others. Luckily, Jest Preview is a free and open source project and we always wecome new contributors. Its mission is to help front end developers' life easier and more enjoyable, also improve the standard of front end applications by encourgaging them to write more high-quality tests, by providng an ability to view the actual UI in Jest in an external browser like Chrome. +Welcome to CONTRIBUTING zone. If you are reading this, you are probably want to contribute to Open Source projects. That's great! Contributing to an open source project is a great opportunity to learn, sharpen your skills and help others. Luckily, Jest Preview is a free and open source project and we always wecome new contributors. Its mission is to help front end developers' lives easier and more enjoyable, also improve the standard of front end applications by encourgaging them to write more high-quality tests, by providng an ability to view the actual UI in Jest in an external browser like Chrome. Jest Preview aims to be a community-driven project. So we hope to see your contributions to make Jest Preview a favourite library for front end developers when it comes to testing. ## What can I contribute? -We appreciated any helps. There are not a thing as small contribution. If you see a typo, send us a PR. If you experience a bug, please open an issue. If you have a suggestion, let us know. Bellow are some ways to contribute to Jest Preview: +We appreciated any helps. There are not a thing as a small contribution. If you see a typo, send us a PR. If you experience a bug, please open an issue. If you have a suggestion, let us know. Bellow are some ways you can contribute to Jest Preview: -- **Submit bugs or issues:**: Software are full of bugs. If you use Jest Preview and find a bug, please open an issue at [Jest Preview's issues](https://github.com/nvh95/jest-preview/issues) -- **Docs**: We have a documentation site at [www.jest-preview.com](https://www.jest-preview.com/docs/getting-started/intro), (draft) it's very easier to contribute to the documentation by using `Edit this page` feature (insert image) -- Fix bugs -- Add new features -- Grammar: not native English speakers. -- Answer questions and issues on GitHub and Discord +- **Submit bugs or issues:**: Software are full of bugs. Jest Preview is no exception. If you use Jest Preview and find a bug, please open an issue at [Jest Preview's issues](https://github.com/nvh95/jest-preview/issues) +- **Docs**: We have a documentation site at [www.jest-preview.com](https://www.jest-preview.com/docs/getting-started/intro), it's very easier to contribute to the documentation by using `Edit this page` button at the bottom of each page. If you see a typo, an unclear page or incorrect grammar, please send us a PR. +- **Fix bugs**: We are tracking bugs at [Issues](https://github.com/nvh95/jest-preview/issues). Please [claim an issue](#claim-issues) then open a PR to fix a bug. +- **Add new features**: You use Jest Preview for your projects and find out Jest Preview is missing a feature? Please open an issue to discuss about it. And it's great if you can help to implement that feature. +- **Answer questions and issues on GitHub and Discord**: [GitHub issues](https://github.com/nvh95/jest-preview/issues) and [Discord](https://discord.gg/X5PyPUfemh) -If not sure what to contribute, Join Discord +If not sure what to contribute, but you still want to contribute something, let us know in [Discord](https://discord.gg/X5PyPUfemh) (channel #contributors) -## Claim issue +## Claim issues -- See docusaurus's docs: https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#claiming-issues +There are some labels worth looking at for a new contributors: -## Run jest-preview locally (Quick start) +- [good first issue](https://github.com/nvh95/jest-preview/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22): Some issues to help you get your feet wet with Jest Preview +- [help wanted](https://github.com/nvh95/jest-preview/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22): if you have specific knowledge in one domain, working on these issues can make your expertise shine. -- npm install -- npm run build:watch -- npm run types (optional to emit types, need to run only once) -- npm run server (to start Jest Preview Server) -- npm run test:only (to run Jest tests at `/demo`) +If you want to work on any of these issues, just drop a message such as "I'd like to work on this". Depends on the difficulty of the issue, it can take a few days or a week to implement the feature/ bug fix. It's great if you can send a PR within seven days. If you need more time on a specific issue, please let us know. After that, we can delegate the issue to someone else if you are not available. -## How jest-preview works - -- See [HOW_JEST_PREVIEW_WORKS.md](./HOW_JEST_PREVIEW_WORKS.md) - -## Repository architecture - -- not use monorepo (yet) -- src -- server -- demo -- config/jest -- dist: build -- examples -- website - TODO: Add absolute link to each folder. - -## Submit a PR - -- Make sure CI passes -- prefer atomic commit -- prefer rebase (avoid merge commits) +## npm scripts -## Closing +Jest Preview repository has some npm scripts to help you develop efficiently. -TODO: To remove `Run jest-preview locally` from README.md +- `npm install`: install all dependencies +- `npm run build:watch`: build `jest-preview` and rebuild it when changes are made +- `npm run types`: emit types, usually only need to run only once +- `npm run server`: start Jest Preview Server +- `npm run test:dev`: run Jest at `/demo/__tests__/App.test.tsx` (you will work with this file most of the time) -draft +## Run locally -Install dependencies +Install dependencies: ```bash npm install ``` -To see the real demo app +Run the real demo app: ```bash npm run dev ``` -Run `jest` and ` jest-preview` simultaneously +Run jest tests and Jest Preview server simultaneously: ```bash npm run test @@ -79,9 +59,41 @@ npm run test Open chrome at http://localhost:3336 to see the preview -However, it's recommend to run `jest` and `jest-preview` separately +However, it's recommend to run jest tests and Jest Preview server separately: ```bash npm run server # Run jest-preview server -npm run test:only # Run jest +npm run test:dev # Run jest ``` + +Whenever `preview.debug()` is triggered, or whenever a test fails, you will see the changes reflected on the browser immediately. + +## How jest-preview works + +- See [HOW_JEST_PREVIEW_WORKS.md](./HOW_JEST_PREVIEW_WORKS.md) + +## Repository architecture + +Following are brief descriptions of the repository architecture: + +- [src](/src/): contains most of the code of Jest Preview such as `debug` function, `jestPreviewConfigure`, all Jest Transformations, preconfigured presets, adapters, etc. +- [server](/server/): contains Jest Preview server code, which is a web server that serves the preview page (Jest Preview Dashboard). +- [demo](/demo/): contains the demo app. You will work with this app most of the time when developing Jest Preview. +- [config/jest](/config/jest/): jest configuration files for the demo app. +- [dist](/dist/): Distribution code, which is bundle and processed by Rollup (previously: Vite Library Mode). +- [examples](/examples/): contains examples of how to integrate Jest Preview with various libraries and frameworks. +- [website](/website/): contains code for [www.jest-preview.com](https://www.jest-preview.com/) + +## Submit a PR + +So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at. + +There are a few things when you open a PR: + +1. Make sure CI passes +2. Prefer atomic commits +3. Prefer rebase over merge: If you create a new branch from `main` and work on it for a while. There is a chance that `main` will be updated and there will be a conflict between `main` and your branch. We would love to have you rebase your branch on top of `main` instead of merging it when your PR is ready. + +## Closing + +We would love to have you in the list of contributors and thank you for your contribution. Happy coding! From ca44c8d1b5dd4a07f35b884687fd07b38a4d9de6 Mon Sep 17 00:00:00 2001 From: Hung Viet Nguyen Date: Wed, 11 May 2022 00:03:22 +0700 Subject: [PATCH 4/8] chore: add a comment to refactor code in the future --- src/preview.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/preview.ts b/src/preview.ts index c30b361c..ec3d85aa 100644 --- a/src/preview.ts +++ b/src/preview.ts @@ -13,6 +13,7 @@ export function debug(element: Element = document.body): void { (prev, current) => prev + current.outerHTML, '', ); + // TODO: Can we just use `document.documentElement.outerHTML` directly. Then, we don't need to save head and body separately. fs.writeFileSync(path.join(CACHE_FOLDER, 'head.html'), headChildrenOnly); // Always save head.html to disk before body.html, so we don't need to watch head.html fs.writeFileSync(path.join(CACHE_FOLDER, 'body.html'), element.outerHTML); From 6b8c87ea07e10db6cc851c2f5c050d8b2909f412 Mon Sep 17 00:00:00 2001 From: Hung Viet Nguyen Date: Wed, 11 May 2022 00:03:44 +0700 Subject: [PATCH 5/8] feat: Update HOW_JEST_PREVIEW_WORK.md --- HOW_JEST_PREVIEW_WORKS.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/HOW_JEST_PREVIEW_WORKS.md b/HOW_JEST_PREVIEW_WORKS.md index e5a8a336..8c6bc32c 100644 --- a/HOW_JEST_PREVIEW_WORKS.md +++ b/HOW_JEST_PREVIEW_WORKS.md @@ -1,21 +1,25 @@ # How Jest Preview Works +## How it works ELI5 + +Jest Preview turns JSDOM to a real DOM and user can see it on a browser. It saved the HTML from JSDOM and serve over a web server (with a web socket connection). It also uses [Jest Tranformations](https://jestjs.io/docs/code-transformation) to handle CSS and files (e.g: images). + ## Components -- Jest Preview Server -- External Browser -- Jest process +- Jest Preview Server: when you run `jest-preview` (`server/previewServer.js`) +- External Browser (Jest Preview Dashboard): e.g: Chrome +- Jest process: `jest` ## How Jest Preview's components interact - - -- Jest process snapshots the app, save html file to `node_modules/.cache/jest-preview`. -- Jest Preview Server serve the html file to the browser. -- If html file changes, Jest Preview Server will send a websocket event to browser to trigger reloading. +- In **Jest process**, whenever `preview.debug()` is triggerd or a test fails in [Automatic Mode](https://www.jest-preview.com/blog/automatic-mode), a html file is saved to `node_modules/.cache/jest-preview`. +- **Jest Preview Server** serve that html file to the **External Browser**. +- If that html file changes, **Jest Preview Server** will send a websocket event to **External Browser** to trigger reloading for newest UI. ## How to display images and CSS +Usually, images and CSS are dropped when testing in Jest. In opposite, Jest Preview tries to keep images and CSS in the Jest tests (JSDOM). + ### Images and CSS imported to components - [Code transformation](https://jestjs.io/docs/code-transformation) From 38ed47d6e456984fa2c0d418d9afbf63d963d3c0 Mon Sep 17 00:00:00 2001 From: Hung Viet Nguyen Date: Wed, 11 May 2022 00:30:50 +0700 Subject: [PATCH 6/8] feat: reuse CONTRIBUTING.md for docusaurus --- CONTRIBUTING.md | 16 ++++++++-------- website/docs/others/contributing.md | 6 ------ website/package.json | 2 +- website/scripts/contributing.js | 13 +++++++++++++ 4 files changed, 22 insertions(+), 15 deletions(-) create mode 100644 website/scripts/contributing.js diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5414433..c38e9340 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,19 +70,19 @@ Whenever `preview.debug()` is triggered, or whenever a test fails, you will see ## How jest-preview works -- See [HOW_JEST_PREVIEW_WORKS.md](./HOW_JEST_PREVIEW_WORKS.md) +- See [HOW_JEST_PREVIEW_WORKS.md](https://github.com/nvh95/jest-preview/tree/main/HOW_JEST_PREVIEW_WORKS.md) ## Repository architecture Following are brief descriptions of the repository architecture: -- [src](/src/): contains most of the code of Jest Preview such as `debug` function, `jestPreviewConfigure`, all Jest Transformations, preconfigured presets, adapters, etc. -- [server](/server/): contains Jest Preview server code, which is a web server that serves the preview page (Jest Preview Dashboard). -- [demo](/demo/): contains the demo app. You will work with this app most of the time when developing Jest Preview. -- [config/jest](/config/jest/): jest configuration files for the demo app. -- [dist](/dist/): Distribution code, which is bundle and processed by Rollup (previously: Vite Library Mode). -- [examples](/examples/): contains examples of how to integrate Jest Preview with various libraries and frameworks. -- [website](/website/): contains code for [www.jest-preview.com](https://www.jest-preview.com/) +- [src](https://github.com/nvh95/jest-preview/tree/main/src/): contains most of the code of Jest Preview such as `debug` function, `jestPreviewConfigure`, all Jest Transformations, preconfigured presets, adapters, etc. +- [server](https://github.com/nvh95/jest-preview/tree/main/server/): contains Jest Preview server code, which is a web server that serves the preview page (Jest Preview Dashboard). +- [demo](https://github.com/nvh95/jest-preview/tree/main/demo/): contains the demo app. You will work with this app most of the time when developing Jest Preview. +- [config/jest](https://github.com/nvh95/jest-preview/tree/main/config/jest/): jest configuration files for the demo app. +- [dist](https://github.com/nvh95/jest-preview/tree/main/dist/): Distribution code, which is bundle and processed by Rollup (previously: Vite Library Mode). +- [examples](https://github.com/nvh95/jest-preview/tree/main/examples/): contains examples of how to integrate Jest Preview with various libraries and frameworks. +- [website](https://github.com/nvh95/jest-preview/tree/main/website/): contains code for [www.jest-preview.com](https://www.jest-preview.com/) ## Submit a PR diff --git a/website/docs/others/contributing.md b/website/docs/others/contributing.md index 5b022132..718a6037 100644 --- a/website/docs/others/contributing.md +++ b/website/docs/others/contributing.md @@ -1,9 +1,3 @@ --- sidebar_position: 2 --- - -# Contributing - -See Contributing guidelines at [CONTRIBUTING.md](https://github.com/nvh95/jest-preview/blob/main/CONTRIBUTING.md) - - diff --git a/website/package.json b/website/package.json index de423caf..1e53ee14 100644 --- a/website/package.json +++ b/website/package.json @@ -5,7 +5,7 @@ "scripts": { "docusaurus": "docusaurus", "start": "docusaurus start", - "build": "docusaurus build", + "build": "node scripts/contributing.js && docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", diff --git a/website/scripts/contributing.js b/website/scripts/contributing.js new file mode 100644 index 00000000..88dab94e --- /dev/null +++ b/website/scripts/contributing.js @@ -0,0 +1,13 @@ +// @ts-check +const fs = require('fs'); + +const rootContributing = '../CONTRIBUTING.md'; +const contributingDoc = './docs/others/contributing.md'; + +const rootContributingContent = fs.readFileSync(rootContributing, 'utf8'); + +// Append to contributingDoc +fs.appendFile(contributingDoc, rootContributingContent, function (err) { + if (err) throw err; + console.log('Saved!'); +}); From b36c20bcb0048688c4c40260477f5cd34a52fb01 Mon Sep 17 00:00:00 2001 From: Hung Viet Nguyen Date: Wed, 11 May 2022 23:35:30 +0700 Subject: [PATCH 7/8] feat: Update docs for how jest preview works --- CONTRIBUTING.md | 2 +- HOW_JEST_PREVIEW_WORKS.md | 14 +++++++------- src/configure.ts | 2 ++ 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c38e9340..10a882fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contribute to Jest Preview +# Contributing ## Welcome diff --git a/HOW_JEST_PREVIEW_WORKS.md b/HOW_JEST_PREVIEW_WORKS.md index 8c6bc32c..c2b12c85 100644 --- a/HOW_JEST_PREVIEW_WORKS.md +++ b/HOW_JEST_PREVIEW_WORKS.md @@ -24,12 +24,12 @@ Usually, images and CSS are dropped when testing in Jest. In opposite, Jest Prev - [Code transformation](https://jestjs.io/docs/code-transformation) - File transformation: Serve source file directly -- CSS transformation: - - CSS Modules - - styled-components - - Sass - - Vanilla CSS +- CSS transformation: Jest Preview turn a css file to a javascript file then try to inject CSS to the `document.head`. Think of Jest Preview try to make any CSS strategy to a CSS-in-JS in Jest. + - CSS Modules: Process via post css then inject the output to the `document.head`. + - Sass: Process by Dart Sass then inject the output to the `document.head`. + - Vanilla CSS: Inject css to the head. +- CSS-in-JS (styled-components, emotion...): Already inject css to the `document.head` by CSS-in-JS themselves. -### Global images and CSS +### Global CSS -- Via `jestPreviewConfigure`. +- Currerntly, CSS outside a rendered component is handled via `jestPreviewConfigure`. The general approach is to save CSS to a file then Jest Preview Server injects it to the preview on demand. This approach is simple and easy to implement. However, the CSS does not appear in the JSDOM, and it's hard to write tests for it. In the future, we would like to move global CSS to the JSDOM (i.e: `document.head`). diff --git a/src/configure.ts b/src/configure.ts index 4bdf0046..afd9e73d 100644 --- a/src/configure.ts +++ b/src/configure.ts @@ -50,6 +50,7 @@ export async function jestPreviewConfigure( // What we encountered is that filename is automatically added `http://localhost` as the prefix // Example: style.scss => http://localhost/style.scss // As a result, sass.compile cannot find the file + // TODO: Can we inject css to the `document.head` directly? exec( `./node_modules/.bin/sass ${cssFile} ${cssDestinationFile} --no-source-map`, (err: any) => { @@ -69,6 +70,7 @@ export async function jestPreviewConfigure( // That way, we can don't have to copy files to disk // Memory is faster than disk anyway!!!! // if (!fs.existsSync(destinationFile)) { + // TODO: Can we inject css to the `document.head` directly? fs.copyFile(cssFile, destinationFile, (err: any) => { if (err) throw err; }); From a9edda22d60a2fd17014fb664a4f229aad2b549e Mon Sep 17 00:00:00 2001 From: Hung Viet Nguyen Date: Fri, 13 May 2022 23:04:16 +0700 Subject: [PATCH 8/8] docs: Update grammar typo --- CONTRIBUTING.md | 22 +++++++++++----------- HOW_JEST_PREVIEW_WORKS.md | 15 ++++++++------- 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 10a882fd..63565f3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,30 +2,30 @@ ## Welcome -Welcome to CONTRIBUTING zone. If you are reading this, you are probably want to contribute to Open Source projects. That's great! Contributing to an open source project is a great opportunity to learn, sharpen your skills and help others. Luckily, Jest Preview is a free and open source project and we always wecome new contributors. Its mission is to help front end developers' lives easier and more enjoyable, also improve the standard of front end applications by encourgaging them to write more high-quality tests, by providng an ability to view the actual UI in Jest in an external browser like Chrome. +Welcome to CONTRIBUTING zone. If you are reading this, you probably want to contribute to Open Source projects. That's great! Contributing to an open source project is a great opportunity to learn, sharpen your skills and help others. Luckily, Jest Preview is a free and open source project and we always welcome new contributors. Its mission is to help front end developers' lives easier and more enjoyable, also improve the standard of front end applications by encouraging them to write more high-quality tests, by providing an ability to view the actual UI in Jest in an external browser like Chrome. -Jest Preview aims to be a community-driven project. So we hope to see your contributions to make Jest Preview a favourite library for front end developers when it comes to testing. +Jest Preview aims to be a community-driven project. So we hope to see your contributions to make Jest Preview a favorite library for front end developers when it comes to testing. ## What can I contribute? -We appreciated any helps. There are not a thing as a small contribution. If you see a typo, send us a PR. If you experience a bug, please open an issue. If you have a suggestion, let us know. Bellow are some ways you can contribute to Jest Preview: +We appreciated any help. There is not a thing as a small contribution. If you see a typo, send us a PR. If you experience a bug, please open an issue. If you have a suggestion, let us know. Below are some ways you can contribute to Jest Preview: -- **Submit bugs or issues:**: Software are full of bugs. Jest Preview is no exception. If you use Jest Preview and find a bug, please open an issue at [Jest Preview's issues](https://github.com/nvh95/jest-preview/issues) +- **Submit bugs or issues:**: Software is full of bugs. Jest Preview is no exception. If you use Jest Preview and find a bug, please open an issue at [Jest Preview's issues](https://github.com/nvh95/jest-preview/issues) - **Docs**: We have a documentation site at [www.jest-preview.com](https://www.jest-preview.com/docs/getting-started/intro), it's very easier to contribute to the documentation by using `Edit this page` button at the bottom of each page. If you see a typo, an unclear page or incorrect grammar, please send us a PR. - **Fix bugs**: We are tracking bugs at [Issues](https://github.com/nvh95/jest-preview/issues). Please [claim an issue](#claim-issues) then open a PR to fix a bug. -- **Add new features**: You use Jest Preview for your projects and find out Jest Preview is missing a feature? Please open an issue to discuss about it. And it's great if you can help to implement that feature. +- **Add new features**: Do you use Jest Preview for your projects and find out Jest Preview is missing a feature? Please open an issue to discuss it. And it's great if you can help to implement that feature. - **Answer questions and issues on GitHub and Discord**: [GitHub issues](https://github.com/nvh95/jest-preview/issues) and [Discord](https://discord.gg/X5PyPUfemh) If not sure what to contribute, but you still want to contribute something, let us know in [Discord](https://discord.gg/X5PyPUfemh) (channel #contributors) ## Claim issues -There are some labels worth looking at for a new contributors: +There are some labels worth looking at for a new contributor: - [good first issue](https://github.com/nvh95/jest-preview/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22): Some issues to help you get your feet wet with Jest Preview - [help wanted](https://github.com/nvh95/jest-preview/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22): if you have specific knowledge in one domain, working on these issues can make your expertise shine. -If you want to work on any of these issues, just drop a message such as "I'd like to work on this". Depends on the difficulty of the issue, it can take a few days or a week to implement the feature/ bug fix. It's great if you can send a PR within seven days. If you need more time on a specific issue, please let us know. After that, we can delegate the issue to someone else if you are not available. +If you want to work on any of these issues, just drop a message such as "I'd like to work on this". Depending on the difficulty of the issue, it can take a few days or a week to implement the feature/ bug fix. It's great if you can send a PR within seven days. If you need more time on a specific issue, please let us know. After that, we can delegate the issue to someone else if you are not available. ## npm scripts @@ -59,7 +59,7 @@ npm run test Open chrome at http://localhost:3336 to see the preview -However, it's recommend to run jest tests and Jest Preview server separately: +However, it's recommended to run jest tests and Jest Preview server separately: ```bash npm run server # Run jest-preview server @@ -76,11 +76,11 @@ Whenever `preview.debug()` is triggered, or whenever a test fails, you will see Following are brief descriptions of the repository architecture: -- [src](https://github.com/nvh95/jest-preview/tree/main/src/): contains most of the code of Jest Preview such as `debug` function, `jestPreviewConfigure`, all Jest Transformations, preconfigured presets, adapters, etc. +- [src](https://github.com/nvh95/jest-preview/tree/main/src/): contains most of the code of Jest Preview such as `debug` function, `jestPreviewConfigure`, all Jest Transformations, pre-configured presets, adapters, etc. - [server](https://github.com/nvh95/jest-preview/tree/main/server/): contains Jest Preview server code, which is a web server that serves the preview page (Jest Preview Dashboard). - [demo](https://github.com/nvh95/jest-preview/tree/main/demo/): contains the demo app. You will work with this app most of the time when developing Jest Preview. - [config/jest](https://github.com/nvh95/jest-preview/tree/main/config/jest/): jest configuration files for the demo app. -- [dist](https://github.com/nvh95/jest-preview/tree/main/dist/): Distribution code, which is bundle and processed by Rollup (previously: Vite Library Mode). +- [dist](https://github.com/nvh95/jest-preview/tree/main/dist/): Distribution code, which is bundled and processed by Rollup (previously: Vite Library Mode). - [examples](https://github.com/nvh95/jest-preview/tree/main/examples/): contains examples of how to integrate Jest Preview with various libraries and frameworks. - [website](https://github.com/nvh95/jest-preview/tree/main/website/): contains code for [www.jest-preview.com](https://www.jest-preview.com/) @@ -96,4 +96,4 @@ There are a few things when you open a PR: ## Closing -We would love to have you in the list of contributors and thank you for your contribution. Happy coding! +We would love to have you on the list of contributors and thank you for your contribution. Happy coding! diff --git a/HOW_JEST_PREVIEW_WORKS.md b/HOW_JEST_PREVIEW_WORKS.md index c2b12c85..f9311699 100644 --- a/HOW_JEST_PREVIEW_WORKS.md +++ b/HOW_JEST_PREVIEW_WORKS.md @@ -2,7 +2,7 @@ ## How it works ELI5 -Jest Preview turns JSDOM to a real DOM and user can see it on a browser. It saved the HTML from JSDOM and serve over a web server (with a web socket connection). It also uses [Jest Tranformations](https://jestjs.io/docs/code-transformation) to handle CSS and files (e.g: images). +Jest Preview turns JSDOM into a real DOM and users can see it on a browser. It saved the HTML from JSDOM and serve over a web server (with a web socket connection). It also uses [Jest Transformations](https://jestjs.io/docs/code-transformation) to handle CSS and files (e.g: images). ## Components @@ -12,9 +12,9 @@ Jest Preview turns JSDOM to a real DOM and user can see it on a browser. It save ## How Jest Preview's components interact -- In **Jest process**, whenever `preview.debug()` is triggerd or a test fails in [Automatic Mode](https://www.jest-preview.com/blog/automatic-mode), a html file is saved to `node_modules/.cache/jest-preview`. -- **Jest Preview Server** serve that html file to the **External Browser**. -- If that html file changes, **Jest Preview Server** will send a websocket event to **External Browser** to trigger reloading for newest UI. +- In **Jest process**, whenever `preview.debug()` is triggered or a test fails in [Automatic Mode](https://www.jest-preview.com/blog/automatic-mode), an html file is saved to `node_modules/.cache/jest-preview`. +- **Jest Preview Server** serves that html file to the **External Browser**. +- If that html file changes, **Jest Preview Server** will send a websocket event to **External Browser** to trigger reloading for the newest UI. ## How to display images and CSS @@ -23,13 +23,14 @@ Usually, images and CSS are dropped when testing in Jest. In opposite, Jest Prev ### Images and CSS imported to components - [Code transformation](https://jestjs.io/docs/code-transformation) -- File transformation: Serve source file directly -- CSS transformation: Jest Preview turn a css file to a javascript file then try to inject CSS to the `document.head`. Think of Jest Preview try to make any CSS strategy to a CSS-in-JS in Jest. +- File transformation: Serve source file directly. For example, an image file is served directly from source code, then it's visible in the Jest Preview Dashboard. +- CSS transformation: Jest Preview turn a css file into a javascript file then try to inject CSS to the `document.head`. Think of Jest Preview tries to make any CSS strategy to a CSS-in-JS in Jest. - CSS Modules: Process via post css then inject the output to the `document.head`. - Sass: Process by Dart Sass then inject the output to the `document.head`. - Vanilla CSS: Inject css to the head. - CSS-in-JS (styled-components, emotion...): Already inject css to the `document.head` by CSS-in-JS themselves. + - Caveat: CSS-in-JS solutions uses Constructable Stylesheet Objects are not supported yet, since the generated CSS are not present in the `document.head`. ### Global CSS -- Currerntly, CSS outside a rendered component is handled via `jestPreviewConfigure`. The general approach is to save CSS to a file then Jest Preview Server injects it to the preview on demand. This approach is simple and easy to implement. However, the CSS does not appear in the JSDOM, and it's hard to write tests for it. In the future, we would like to move global CSS to the JSDOM (i.e: `document.head`). +- Currently, CSS outside a rendered component is handled via `jestPreviewConfigure`. The general approach is to save CSS to a file then Jest Preview Server injects it to the preview on demand. This approach is simple and easy to implement. However, the CSS does not appear in the JSDOM, and it's hard to write tests for it. In the future, we would like to move global CSS to the JSDOM (i.e: `document.head`).