From 1cd25c7930c11b4669f59bb8f714f576710405a2 Mon Sep 17 00:00:00 2001 From: Brooke Rhodes Date: Mon, 4 Mar 2024 18:30:22 +0000 Subject: [PATCH] docs: Align docs with community tools and expectations (#5) * feat: Update README.md * docs: Replace Jest Roblox references with Jest Lua * ci: Setup docs deployment * docs: Update version * docs: Align with community --- .github/workflows/docs.yml | 37 + .gitignore | 1 - CHANGELOG.md | 6 +- Docs.md | 12 +- README.md | 52 +- docs/README.md | 33 - docs/docs/CLI.md | 11 +- docs/docs/Configuration.md | 34 +- docs/docs/Deviations.md | 6 +- docs/docs/ExpectAPI.md | 16 +- docs/docs/GettingStarted.md | 60 +- docs/docs/GlobalAPI.md | 18 +- docs/docs/JestBenchmarkAPI.md | 6 +- docs/docs/JestObjectAPI.md | 8 +- docs/docs/SetupAndTeardown.md | 8 +- docs/docs/SnapshotTesting.md | 21 +- docs/docs/TestEZMigration.md | 52 +- docs/docs/TestingAsyncCode.md | 8 +- docs/docs/TimerMocks.md | 6 +- docs/docs/UpgradingToJest3.md | 51 +- docs/docs/UsingMatchers.md | 7 +- docs/docusaurus.config.js | 24 +- docs/package.json | 11 +- docs/yarn.lock | 11764 +++++++++++++++++++++++++++++++ src/expect/README.md | 2 +- src/jest-fake-timers/README.md | 6 +- src/jest-snapshot/README.md | 4 +- 27 files changed, 12023 insertions(+), 241 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 docs/README.md create mode 100644 docs/yarn.lock diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..b2405a2a --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,37 @@ +name: Docs + +on: + push: + branches: + - main + +permissions: + contents: write + +jobs: + deploy: + name: Deploy to GitHub Pages + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-node@v4 + with: + node-version: 18 + cache: yarn + + - name: Install dependencies + run: yarn install --frozen-lockfile + working-directory: ./docs + - name: Build website + run: yarn build + working-directory: ./docs + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/build + user_name: github-actions[bot] + user_email: 41898282+github-actions[bot]@users.noreply.github.com \ No newline at end of file diff --git a/.gitignore b/.gitignore index 30918cd5..0d2d1a09 100644 --- a/.gitignore +++ b/.gitignore @@ -32,7 +32,6 @@ Packages/* /docs/.docusaurus /docs/build /docs/node_modules -/docs/yarn.lock # Selene roblox.toml diff --git a/CHANGELOG.md b/CHANGELOG.md index caf659f7..e4333948 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -# Jest Roblox Changelog +# Jest Lua Changelog ## Unreleased Changes @@ -209,7 +209,7 @@ * Added `toMatchSnapshot` matcher * Added `toThrowErrorMatchingSnapshot` matcher * Added custom snapshot matchers and property matchers, refer to the "Snapshot Testing" section of the documentation for more info - * Added `UPDATESNAPSHOT` flag for updating snapshots, the value can either be `all` (by default), or `new` to only add new snapshots, this can be enabled with an `--updateSnapshot` flag in Jest Roblox CLI + * Added `UPDATESNAPSHOT` flag for updating snapshots, the value can either be `all` (by default), or `new` to only add new snapshots, this can be enabled with an `--updateSnapshot` flag in Jest Lua CLI * :rotating_light: Removed colon syntax alias for initializing mock functions * :hammer_and_wrench: `--fastFlags.overrides "UseDateTimeType3=true"` removed as it is no longer needed * :bug: Fix issue with CoreScriptConverter and the Modules directory ([#79](https://github.com/Roblox/jest-roblox-internal/pull/79)) @@ -269,7 +269,7 @@ expect().toReturnWith() also aliased as expect().toHaveReturnedWith() * :sparkles: Added `expect().toThrow()` ([#30](https://github.com/Roblox/jest-roblox-internal/pull/30)) ## 0.5.0 (2021-01-29) -* :sparkles: Initial release of Jest Roblox, TestEZ has been rebranded as of this release. +* :sparkles: Initial release of Jest Lua, TestEZ has been rebranded as of this release. * :sparkles: Added `expect` aligned to [Jest's expect (26.5.3)](https://jestjs.io/docs/en/26.5/expect) * Requires an explicit `require` from [`JestRoblox.Globals`](https://jestjs.io/docs/en/26.5/api) to use * Refer to the Jest documentation on expect for usage documentation. Refer to the `README.md` in `src/Modules/expect` for details on deviations from upstream diff --git a/Docs.md b/Docs.md index 4c22db0a..32bf6426 100644 --- a/Docs.md +++ b/Docs.md @@ -1,13 +1,13 @@ -# Jest Roblox Docs +# Jest Lua Docs -The Jest Roblox API is similar to [the API used by JavaScript Jest.](https://jestjs.io/docs/27.x/api) +The Jest Lua API is similar to [the API used by JavaScript Jest.](https://jestjs.io/docs/27.x/api) # Usage -Jest Roblox doesn't inject any global variables. Every jest functionality needs to be imported from `JestGlobals`. For example: +Jest Lua doesn't inject any global variables. Every jest functionality needs to be imported from `JestGlobals`. For example: ```lua -local JestGlobals = require(Packages.Dev.JestGlobals) +local JestGlobals = require("@DevPackages/JestGlobals") local describe = JestGlobals.describe local expect = JestGlobals.expect @@ -444,13 +444,13 @@ Should be the same taking into account [not supported matchers](#expect) ### [Promises](https://jestjs.io/docs/27.x/asynchronous#promises) -Tests can return a [Promise](https://github.com/evaera/roblox-lua-promise) and Jest Roblox will wait for the promise to resolve. +Tests can return a [Promise](https://github.com/evaera/roblox-lua-promise) and Jest Lua will wait for the promise to resolve. > **Note:** It is also worth noting that tests can ONLY return either a `Promise` or `nil`. ### [Callbacks](https://jestjs.io/docs/27.x/asynchronous#callbacks) -Jest Roblox supports `done` callback as a second param to the test function +Jest Lua supports `done` callback as a second param to the test function eg. ```lua diff --git a/README.md b/README.md index 985e0c6f..164e004f 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,44 @@ -

Jest Roblox

-
- - GitHub Actions Build Status - - - Documentation - - - Coverage Status - -
+ -
- Lovely Lua Testing -
+# Jest Lua -
 
+

Delightful Lua Testing.

-Jest Roblox can run within Roblox itself, as well as inside roblox-cli for testing on CI systems. +[![Tests](https://github.com/jsdotlua/jest-lua/actions/workflows/test.yml/badge.svg)](https://github.com/jsdotlua/jest-lua/actions/workflows/test.yml) + +[![Docs](https://img.shields.io/badge/docs-website-green.svg)](https://jsdotlua.github.io/jest-lua/) -We use Jest Roblox at Roblox for testing our apps, in-game core scripts, built-in Roblox Studio plugins, as well as libraries like [Roact Navigation](https://github.com/Roblox/roact-navigation). +--- + +Jest Lua can currently only run inside of Roblox. Help is wanted to get it running in other Lua environments, such as [Lune](https://lune.gitbook.io/lune/) or [Luvit](https://luvit.io/). See issue [#2](https://github.com/jsdotlua/jest-lua/issues/2). + +Roblox uses Jest Lua internally for testing their apps, in-game core scripts, built-in Roblox Studio plugins, as well as libraries like [Roact Navigation](https://github.com/Roblox/roact-navigation). This library should be considered battle-tested and ready for production use. --- -Add this package to your `dev_dependencies` in your `rotriever.toml`, for example: -``` -JestGlobals = "github.com/Roblox/jest-roblox@2.2.0" +# Installation + +Add this package to your `dev-dependencies` in your `wally.toml`, for example: + +```toml +JestGlobals = "jsdotlua/jest-globals@3.6.1-rc.2" ``` Then, require anything you need from `JestGlobals`: -``` -local JestGlobals = require(Packages.JestGlobals) + +```lua +local JestGlobals = require("@Packages/JestGlobals") local expect = JestGlobals.expect ``` ---- - ## Inspiration and Prior Work -Jest Roblox is a Roblox port of the open source JavaScript testing framework [Jest](https://github.com/facebook/jest). Modules in the `modules` directory are aligned to [v27.4.7](https://github.com/facebook/jest/tree/v27.4.7) of Jest. ---- +Jest Lua is a Lua port of the open source JavaScript testing framework [Jest](https://github.com/facebook/jest). Modules in the `modules` directory are aligned to [v27.4.7](https://github.com/facebook/jest/tree/v27.4.7) of Jest. ## Contributing + Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for information. ## License -Jest Roblox is available under the MIT license. See [LICENSE](LICENSE) for details. + +Jest Lua is available under the MIT license. See [LICENSE](LICENSE) for details. diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index ca50e936..00000000 --- a/docs/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# Website - -This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator. - -## Installation - -```console -yarn install -``` - -## Local Development - -```console -yarn start -``` - -This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server. - -## Build - -```console -yarn build -``` - -This command generates static content into the `build` directory and can be served using any static contents hosting service. - -## Deployment - -```console -GIT_USER= GIT_PASS= yarn deploy -``` - -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. diff --git a/docs/docs/CLI.md b/docs/docs/CLI.md index 56572766..a5b3713a 100644 --- a/docs/docs/CLI.md +++ b/docs/docs/CLI.md @@ -4,10 +4,11 @@ title: runCLI Options ---

Jest

Deviation -The `Jest` packages exports `runCLI`, which is the main entrypoint to run Jest Roblox tests. In your entrypoint script, import `runCLI` from the `Jest` package. A basic entrypoint script can look like the following: +The `Jest` packages exports `runCLI`, which is the main entrypoint to run Jest Lua tests. In your entrypoint script, import `runCLI` from the `Jest` package. A basic entrypoint script can look like the following: + ```lua title="spec.lua" local Packages = script.Parent.YourProject.Packages -local runCLI = require(Packages.Dev.Jest).runCLI +local runCLI = require("@Packages/Jest").runCLI local processServiceExists, ProcessService = pcall(function() return game:GetService("ProcessService") @@ -35,7 +36,7 @@ end return nil ``` -The first argument to `runCLI` is the root directory of your project, the second argument is a list of [options](#options), and the third argument is a list of projects (directories with a `jest.config.lua`) for Jest Roblox to discover. +The first argument to `runCLI` is the root directory of your project, the second argument is a list of [options](#options), and the third argument is a list of projects (directories with a `jest.config.lua`) for Jest Lua to discover. ## Options @@ -50,7 +51,7 @@ import TOCInline from "@theme/TOCInline"; ### `ci` \[boolean] Jest Aligned -When this option is provided, Jest Roblox will assume it is running in a CI environment. This changes the behavior when a new snapshot is encountered. Instead of the regular behavior of storing a new snapshot automatically, it will fail the test and require Jest Roblox to be run with `updateSnapshot`. +When this option is provided, Jest Lua will assume it is running in a CI environment. This changes the behavior when a new snapshot is encountered. Instead of the regular behavior of storing a new snapshot automatically, it will fail the test and require Jest Lua to be run with `updateSnapshot`. ### `clearMocks` \[boolean] Jest Aligned @@ -75,7 +76,7 @@ Prints the test results in JSON. This mode will send all other test output and u ### `listTests` \[boolean] Jest Aligned -Lists all test files that Jest Roblox will run given the arguments, and exits. +Lists all test files that Jest Lua will run given the arguments, and exits. ### `noStackTrace` \[boolean] Jest Aligned diff --git a/docs/docs/Configuration.md b/docs/docs/Configuration.md index 0d2136d8..66019575 100644 --- a/docs/docs/Configuration.md +++ b/docs/docs/Configuration.md @@ -4,7 +4,7 @@ title: Configuring Jest ---

Jest

-The Jest Roblox philosophy is to work great by default, but sometimes you just need more configuration power. +The Jest Lua philosophy is to work great by default, but sometimes you just need more configuration power. deviation @@ -56,7 +56,7 @@ return { } ``` -Alternatively, a table with the keys `name` and `color` can be passed. This allows for a custom configuration of the background color of the displayName. `displayName` defaults to white when its value is a string. Jest Roblox uses [`chalk-lua`](https://github.com/Roblox/chalk-lua) to provide the color. As such, all of the valid options for colors supported by `chalk-lua` are also supported by Jest Roblox. +Alternatively, a table with the keys `name` and `color` can be passed. This allows for a custom configuration of the background color of the displayName. `displayName` defaults to white when its value is a string. Jest Lua uses [`chalk-lua`](https://github.com/Roblox/chalk-lua) to provide the color. As such, all of the valid options for colors supported by `chalk-lua` are also supported by Jest Lua. ```lua return { @@ -72,7 +72,7 @@ return { Default: `nil` -When the `projects` configuration is provided with an array of instances, Jest Roblox will run tests in all of the specified projects at the same time. This is great for monorepos or when working on multiple projects at the same time. +When the `projects` configuration is provided with an array of instances, Jest Lua will run tests in all of the specified projects at the same time. This is great for monorepos or when working on multiple projects at the same time. ```lua return { @@ -80,7 +80,7 @@ return { } ``` -This example configuration will run Jest Roblox in the `ProjectA` as well as the `ProjectB` directories. You can have an unlimited amount of projects running in the same Jest Roblox instance. +This example configuration will run Jest Lua in the `ProjectA` as well as the `ProjectB` directories. You can have an unlimited amount of projects running in the same Jest Lua instance. :::tip @@ -98,13 +98,13 @@ Automatically restore mock state and implementation before every test. Equivalen ### `rootDir` \[Instance] Jest API change -Default: The root of the directory containing your Jest Roblox [config file](#). +Default: The root of the directory containing your Jest Lua [config file](#). -The root directory that Jest Roblox should scan for tests and modules within. +The root directory that Jest Lua should scan for tests and modules within. Oftentimes, you'll want to set this to your main workspace, corresponding to where in your repository the code is stored. -