From 274459c23901cd97312f538b5c0e502d259f71a6 Mon Sep 17 00:00:00 2001 From: BenceSzalai Date: Tue, 12 Sep 2023 00:59:04 +0200 Subject: [PATCH] docs: various improvements and fixes in documentation --- CHANGELOG.md | 15 +++++++++++---- README.md | 43 ++++++++++++++++++++----------------------- package.json | 2 +- 3 files changed, 32 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e2f9ffd..12d1516 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,8 +5,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] + +## [29.0.0] - 2023-09-12 ### Docs -- Typo in `README.md`. +- Improved grammar of `README.md`. +- Fixed wrong links in this `CHANGELOG.md`. + +### Fix +- Mark Peer Dependencies optional to eliminate warnings during installation. ## [29.0.0-rc.1] - 2023-08-22 ### Fix @@ -22,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 -[Unreleased]: https://github.com/BenceSzalai/vue-components-ide-helper/compare/29.0.0-rc.1...HEAD -[29.0.0-rc.1]: https://github.com/BenceSzalai/vue-components-ide-helper/compare/29.0.0-rc.0...29.0.0-rc.1 -[29.0.0-rc.0]: https://github.com/BenceSzalai/vue-components-ide-helper/releases/tag/29.0.0-rc.0 +[Unreleased]: https://github.com/sbnc-eu/jest-skip/compare/29.0.0...HEAD +[29.0.0]: https://github.com/sbnc-eu/jest-skip/compare/29.0.0-rc.1...29.0.0 +[29.0.0-rc.1]: https://github.com/sbnc-eu/jest-skip/compare/29.0.0-rc.0...29.0.0-rc.1 +[29.0.0-rc.0]: https://github.com/sbnc-eu/jest-skip/releases/tag/29.0.0-rc.0 diff --git a/README.md b/README.md index 2309f79..8c10baf 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,44 @@ # Jest Skip -Add the ability to Jest to dynamically skip tests during the test execution. +This package extends Jest's functionality by allowing dynamic skipping of tests during test execution. -## Explanation +## Overview -Sometimes we want to skip a test based on some condition. For example, we may want to skip a test if the environment is not set up properly or if some other tests have failed. This is not possible with Jest out of the box, but this utility adds this functionality. +There are instances when we may need to skip a test based on certain conditions. For example, if the environment isn't properly set up or if other tests have failed. While Jest doesn't support this feature natively, this utility provides the functionality. -This small utility attempts to solve that problem in the following way: -* it includes a custom test environment which marks tests as skipped when needed -* it includes a `skip()` and a `skipIf()` function which can be used to skip tests +This utility addresses the issue by: +* Including a custom test environment that marks tests as skipped when necessary. +* Providing `skip()` and `skipIf()` functions that can be used to skip tests. ## Disclaimer -The [`jest-circus` documentation](https://github.com/jestjs/jest/tree/main/packages/jest-circus#overview) explicitly says that mutating the state data by the environment is not supported. This utility does exactly that, so it may break in the future or not work at all in some cases. +The [`jest-circus` documentation](https://github.com/jestjs/jest/tree/main/packages/jest-circus#overview) explicitly states that mutating the state data by the environment is unsupported. This utility does exactly that, so it may not work in some cases or could break in the future. -Use it at your own risk! +Use at your own risk! -In reality Jest seems to be perfectly fine with such mutations, or at least the kind of mutations this utility does, so it will most probably work for you too. Indeed, if something does not work, feel free to raise an issue! +In practice, Jest seems to handle such mutations well, especially those performed by this utility. Therefore, it should work for you too. However, if something doesn't work, feel free to raise an issue! ## Usage ### Installation -Install using e.g. npm: +Install using npm or your preferred package manager, e.g.: `npm install --save-dev @sbnc/jest-skip` -... or your choice of package manager. - ### Configuration #### Prerequisite -Please make sure you understand what a [Jest Environment](https://jestjs.io/docs/configuration#testenvironment-string) is and how to use it. +Ensure you understand what a [Jest Environment](https://jestjs.io/docs/configuration#testenvironment-string) is and how to use it. -Since this utility is a Jest Environment replacement, you need to set it up in your Jest configuration file or in your test files. +As this utility replaces the Jest Environment, you need to configure it in your Jest configuration file or in your test files. -Now since we are replacing the Jest Environment this eliminates your ability to choose your Environment freely. This utility supports the most common environments: +Since we're replacing the Jest Environment, it limits your ability to freely choose your Environment. This utility supports the most common environments: - `node`: `@sbnc/jest-skip/node` - `jsdom`: `@sbnc/jest-skip/jsdom` -If you'd like to use it with a different environment, such as [`@happy-dom/jest-environment`](https://www.npmjs.com/package/@happy-dom/jest-environment), please raise an issue or a pull request. - +If you want to use it with a different environment, such as [`@happy-dom/jest-environment`](https://www.npmjs.com/package/@happy-dom/jest-environment), please raise an issue or a pull request. #### CLI @@ -52,7 +49,7 @@ Specify the environment as a CLI argument for the Jest command: #### In `package.json` -Add the following to your `package.json` file to configure for all tests: +To configure for all tests, add the following to your `package.json` file: ```json { @@ -83,7 +80,7 @@ Or if you are using `json`: #### Test file -Add the following to your test file to only use it in certain test files: +To use it in certain test files only, add the following to your test file: ```js /** @@ -95,7 +92,7 @@ Add the following to your test file to only use it in certain test files: ### `skip()` -This method skips a test unconditionally. It can be used on its own or inside custom logic. +This method unconditionally skips a test. It can be used on its own or within custom logic. ```js import { skip } from '@sbnc/jest-skip'; @@ -108,7 +105,7 @@ test('skipped test', () => { ### `skipIf()` -This method skips a test if the condition is met. It can be used on its own or inside custom logic. +This method skips a test if the condition is met. It can be used on its own or within custom logic. ```js import { skipIf } from '@sbnc/jest-skip'; @@ -121,9 +118,9 @@ test('test only when someCondition is not true', () => { ### CJS vs ESM support -The environments are packaged in only CJS format, since Jest is still a CJS application, and currently I know of no use-cases where the environment should be in ESM format. +The environments are packaged in only CJS format, as Jest is still a CJS application. Currently, there are no use-cases where the environment should be in ESM format. -The utilities are shipped in both CJS and ESM formats, so beside the examples above +The utilities are shipped in both CJS and ESM formats. So, besides the examples above, ```js const { skip, skipIf } = require('@sbnc/jest-skip'); ``` diff --git a/package.json b/package.json index 17295ff..72df79e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@sbnc/jest-skip", - "version": "29.0.0-rc.1", + "version": "29.0.0", "description": "Jest environment and test utilities to conditionally skip tests.", "license": "MIT", "keywords": [