update docs

Author: nissy-dev

README.md

@@ -2,6 +2,8 @@
 
 Tenbin provides tools to minimize the differences in test execution times across shards.
 
+![Tenbin provides tools to minimize the differences in test execution times across shards.](./assets/tenbin-abstract.png)
+
 ## Usage
 
 - [Jest](./packages/jest/README.md)

assets/tenbin-abstract.png

@@ -5,7 +5,7 @@ type Partition<T> = {
 
 /**
  * Partition data into k partitions such that the difference between the sum of the values of each partition is minimized.
- * see: https://en.wikipedia.org/wiki/Largest_differencing_method
+ * cf: https://en.wikipedia.org/wiki/Largest_differencing_method
  */
 export function partition<T>(
   data: T[],

packages/core/src/index.ts

@@ -4,13 +4,39 @@
 
 ## Usage
 
+This package provide two modules:
+
+### `TenbinReporter`
+
+This module is served as the default export from `@tenbin/jest/reporter`.
+
+`TenbinReporter` generates a JSON report showing the execution time (in seconds) for each test file, as shown below:
+
+```json:tenbin-report.json
+{
+  "tests/file-a.test.ts": 1.223,
+  "tests/file-b.test.ts": 2.334,
+  ...
+}
+```
+
+The report is saved as `tenbin-report.json` in the current working directory (cwd). This file is uploaded to external storage, such as S3, and is used by `TenbinSequencer` when running next tests. In the case of GitHub Actions, the file can be stored using a cache that persists between workflows. (See the Example section for details.)
+
+### `TenbinSequencer`
+
+This module is served as the default export from `@tenbin/jest/sequencer`.
+
+`TenbinSequencer` reads the `tenbin-report.json` file from the current working directory (cwd) and splits tests to minimize the differences in test execution times across shards For test files not listed in `tenbin-report.json`, the execution time is assumed to be 0 seconds. If the tenbin-report.json file is not found, the shards are split randomly.
+
+## Example
+
 Install:
 
 ```sh
 npm i @tenbin/jest -D
 ```
 
-Jest configuration:
+Configuration:
 
 ```js
 /** @type {import('jest').Config} */
@@ -50,8 +76,8 @@ jobs:
         run: pnpm install
       - name: Run build
         run: pnpm run build
-      # Restore the tenbin-report.json file, which records the execution time of each test file.
-      # @tenbin/jest/sequencer use this file for sharding.
+      # Restore stenbin-report.json file, which records the execution time of each test file.
+      # @tenbin/jest/sequencer uses this file for sharding.
       - name: Restore tenbin-report.json
         id: tenbin-report-cache
         uses: actions/cache/restore@v4
@@ -62,7 +88,7 @@ jobs:
             tenbin-report-*
       - name: Run test
         run: pnpx jest --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
-      # @tenbin/jest/reporter generates a tenbin-report.json for each shard.
+      # @tenbin/jest/reporter generates tenbin-report.json for each shard.
       - name: Upload tenbin-report.json
         if: github.ref_name == 'main'
         uses: actions/upload-artifact@v4

packages/jest/README.md

@@ -4,13 +4,40 @@
 
 ## Usage
 
+This package provides one function:
+
+### `splitTests`
+
+`splitTests` function divides test files based on the past [Playwright JSON report](https://playwright.dev/docs/test-reporters#json-reporter) specified in `reportFile`. It considers only files matching the `pattern` and ensures that each split has a balanced total execution time.
+
+```ts
+import { defineConfig } from "@playwright/test";
+import { splitTests } from "@tenbin/playwright";
+
+export default defineConfig({
+  testMatch: splitTests({
+    shard: "1/3",
+    pattern: ["tests/**.test.ts"],
+    reportFile: "./test-results.json",
+  }),
+});
+```
+
+Options:
+
+- `shard`: test suite shard to execute in a format of `<index>/<count>`
+- `pattern`: glob pattern that defines which test files should be executed
+- `reportFile`: path to previous Playwright JSON report
+
+## Example
+
 Install:
 
 ```sh
 npm i @tenbin/playwright -D
 ```
 
-Playwright configuration:
+Configuration:
 
 ```js
 import { defineConfig } from "@playwright/test";
@@ -55,7 +82,7 @@ jobs:
       - name: Run build
         run: pnpm run build
       # Restore test-results.json file, which records the execution time of each test file.
-      # splitTests function use this file for sharding.
+      # splitTests function uses this file for sharding.
       - name: Restore test-results.json
         uses: actions/cache/restore@v4
         with:

packages/playwright/README.md

@@ -4,13 +4,39 @@
 
 ## Usage
 
+This package provide two modules:
+
+### `TenbinReporter`
+
+This module is served as the default export from `@tenbin/vitest/reporter`.
+
+`TenbinReporter` generates a JSON report showing the execution time (in seconds) for each test file, as shown below:
+
+```json:tenbin-report.json
+{
+  "tests/file-a.test.ts": 1.223,
+  "tests/file-b.test.ts": 2.334,
+  ...
+}
+```
+
+The report is saved as `tenbin-report.json` in the current working directory (cwd). This file is uploaded to external storage, such as S3, and is used by `TenbinSequencer` when running next tests. In the case of GitHub Actions, the file can be stored using a cache that persists between workflows. (See the Example section for details.)
+
+### `TenbinSequencer`
+
+This module is served as the default export from `@tenbin/vitest/sequencer`.
+
+`TenbinSequencer` reads the `tenbin-report.json` file from the current working directory (cwd) and splits tests to minimize the differences in test execution times across shards For test files not listed in `tenbin-report.json`, the execution time is assumed to be 0 seconds. If the tenbin-report.json file is not found, the shards are split randomly.
+
+## Example
+
 Install:
 
 ```sh
 npm i @tenbin/vitest -D
 ```
 
-Vitest configuration:
+Configuration:
 
 ```ts
 import TenbinReporter from "@tenbin/vitest/reporter";
@@ -55,8 +81,8 @@ jobs:
         run: pnpm install
       - name: Run build
         run: pnpm run build
-      # Restore the tenbin-report.json file, which records the execution time of each test file.
-      # @tenbin/vitest/sequencer use this file for sharding.
+      # Restore tenbin-report.json file, which records the execution time of each test file.
+      # @tenbin/vitest/sequencer uses this file for sharding.
       - name: Restore tenbin-report.json
         id: tenbin-report-cache
         uses: actions/cache/restore@v4
@@ -67,7 +93,7 @@ jobs:
             tenbin-report-*
       - name: Run test
         run: pnpx vitest --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
-      # @tenbin/vitest/reporter generates a tenbin-report.json for each shard.
+      # @tenbin/vitest/reporter generates tenbin-report.json for each shard.
       - name: Upload tenbin-report.json
         if: github.ref_name == 'main'
         uses: actions/upload-artifact@v4