Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(devs-infra): release docs for v29.0.0 #3799

Merged
merged 1 commit into from
Sep 9, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions website/versioned_docs/version-29.0/babel7-or-ts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
---
id: babel7-or-ts
title: Babel7 or TypeScript
---

In Sept. 2018 Babel7 got released with an interesting preset: `@babel/preset-typescript`.

The goal is to make it easy for users using Babel to try TypeScript without moving out from Babel, just by adding a preset in their Babel config (here is the [MSDN blog post](https://blogs.msdn.microsoft.com/typescript/2018/08/27/typescript-and-babel-7/) about TypeScript and Babel 7).

## Limitations

While `@babel/preset-typescript` is a great preset, you must know the limitation of it. Here is what is possible with TypeScript (and `ts-jest`), which is not with Babel7 and `@babel/preset-typescript`:

#### No type-checking

This is the big **PRO** of using TypeScript vs Babel, you have type-checking out of the box.

You'll get a more fluent TDD experience (when using `ts-jest`) since files will be type-checked at the same time they're compiled and ran.

Here TypeScript will throw while Babel won't:

```ts
const str: string = 42
```

With Babel, files are transpiled as isolated modules, there is no notion of "project". With TypeScript, files are part of a project and are compiled in that scope.

---

#### No `namespace`

```ts
namespace app {
export const VERSION = '1.0.0'
export class App {
/* ... */
}
}
```

---

#### No `const enum`

```ts
const enum Directions {
Up,
Down,
Left,
Right,
}
```

---

#### No declaration merging (`enum`, `namespace`, ...)

You won't be able to do [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html).

---

#### No legacy `import`/`export`

```ts
import lib = require('lib')
// ...
export = myVar
```

---

#### No caret type-casting with JSX enabled

```ts
const val = <string>input
```
174 changes: 174 additions & 0 deletions website/versioned_docs/version-29.0/contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
---
id: contributing
title: Contributing
---

When contributing to this repository, please first discuss the change you wish to make via [`ts-jest` GitHub discussion](https://github.com/kulshekhar/ts-jest/discussions) or [issue](https://github.com/kulshekhar/ts-jest/issues) with the owners of this repository before making a change.

Please note we have a code of conduct, please follow it in all your interactions with the project.

## Pull Request Process

1. Ensure the tests are passing and that you have latest `main` branch merged in.
2. Update the `docs/` with details of your changes if required.
3. If possible, squash your commits. There must be only one commit in your PR (until a review). Then after each review requesting changes, DO NOT squash your commits with the one before the review, so that we can see intermediate modifications.
4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.

_These are internal technical documents. If you're not a contributor to `ts-jest`, but simply trying to use the library you'll find nothing of value here_

## E2E Testing

### Preparing

The preparation of E2E test directory is done in `scripts/e2e.js`. Here is the process:

```plantuml
start

:bundle ts-jest;
note right
will build ts-jest before creating the bundle
end note

:create temp work dir;
note right
`e2e/~__workdir_symlink__` links to it
except on CI environments
end note

while (for each template)
note right
templates are in `e2e/~__templates__/`
end note

if (template's build directory) then (exists)
:wipe but `node_modules` dir;
else (not exists)
:create;
endif

:copy files from template's dir to its build dir;

if (package lock file) then (exists)
:read metadata;

if (package lock file) then (has changed)
:remove `node_modules` dir;

:npm install (or ci);

:npm install ts-jest bundle;

else if (ts-jest bundle) then (has changed)
:npm install ts-jest bundle;

else (hasn't changed)
endif
:write updated metadata;

else (not exists)
endif

endwhile (done)

:all templates ready;

stop
```

### Running

When a test-case needs to be run with a given template within tests, here is what's happening (in `e2e/__helpers__/test-case/runtime.ts`):

```plantuml
start

:create work dir;
note right
It'll be different per test-case
and per template basis.
end note
-> e2e/~__workdir_symlink__/{template}/{test-case};

if (has a node_modules dir?) then (yes)
:symlink node_modules;
note left
avoid re-running npm install
for each test case and template;
end note
else (no)
endif

:copy files from template;
note right
all files in template dir are
copied to test case work dir
except `node_modules` and
`package-lock.json`
end note

while (for each file in test case dir)
if (is snapshot dir) then (yes)
:symlink dir;
note left
snapshots directories are symlinked
to test case source dir so that
updating them would update in the
source folder
end note

else if (is jest.config.js) then (yes)
if (jest.config.js is function?) then (yes)
:call with parent content;
note left
allows for
extending
end note
else (no)
endif

else (others)
:copy;
note right
all files in test case source
dir are copied to the work dir
except `node_modules` and
`package-lock.json`
end note

endif
endwhile

:create special files;
note right
some special files are created
to handle hooks for example and
grab `process()` IO for later
expectations
end note

:update package.json;
note right
set a custom but fixed name
and version in package.json
which is specific to the
test case + template
end note

#tomato:run tests;

while (for each snapshot) is (missing in test case)
:copy;
note right
while we symlinked each snapshots
directory, newly created snapshots
in non existing dir will need to
be copied over into
e2e/~__cases__/{test-case}
end note
endwhile

:return results;

stop
```
30 changes: 30 additions & 0 deletions website/versioned_docs/version-29.0/debugging.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
---
id: debugging
title: Debugging ts-jest
---

You can activate the debug logger by setting the environment variable `TS_JEST_LOG` before running tests.
The output of the logger will be in **ts-jest.log** in current working directory.

The debug logger contains some useful information about how internal `ts-jest` works, including which files are processed,
which Jest config or TypeScript config is used etc.

**Linux/MacOS**

```
export TS_JEST_LOG=ts-jest.log
```

**Windows**

Command Prompt (cmd)

```
set TS_JEST_LOG=ts-jest.log
```

PowerShell

```
$env:TS_JEST_LOG = 'ts-jest.log'
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
id: installation
title: Installation
---

### Dependencies

You can install `ts-jest` and dependencies all at once with one of the following commands.

#### NPM

```sh
npm install --save-dev jest typescript ts-jest @types/jest
```

#### Yarn

```sh
yarn add --dev jest typescript ts-jest @types/jest
```

:::tip

Tip: If you get an error with the following `npm` commands such as `npx: command not found`, you can replace `npx XXX` with `node node_modules/.bin/XXX` from the root of your project.

:::

### Jest config file

#### Creating

By default, Jest can run without any config files, but it will not compile `.ts` files.
To make it transpile TypeScript with `ts-jest`, we will need to create a configuration file that will tell Jest to use a `ts-jest` preset.

`ts-jest` can create the configuration file for you automatically:

#### NPM

```sh
npx ts-jest config:init
```

#### Yarn

```sh
yarn ts-jest config:init
```

This will create a basic Jest configuration file which will inform Jest about how to handle `.ts` files correctly.

You can also use the `jest --init` command (prefixed with either `npx` or `yarn` depending on what you're using) to have more options related to Jest.
However, answer `no` to the Jest question about whether or not to enable TypeScript. Instead, add the line: `preset: "ts-jest"` to the `jest.config.js` file afterwards.

#### Customizing

For customizing jest, please follow their [official guide online](https://jestjs.io/docs/en/configuration.html).

`ts-jest` specific options can be found [here](options).
Loading