@schwabyio/gta 0.13.0 → 0.14.1

package/README.md

@@ -23,7 +23,7 @@ The package has no dependencies to install: everything `gta` uses is bundled int
 
 ## A first project
 
-A project is a folder holding a `collections/` directory, an `environments/` one and a
+A project is a folder holding a `collections/` folder, an `environments/` one and a
 `settings.yml`. The smallest project `gta` runs is three files:
 
 ```yaml
@@ -139,6 +139,43 @@ In a monorepo, projects that share a global project (`uses:` in `project.yml`) s
 setting by setting it again in its own file. Each project still needs a `settings.yml`,
 even an empty one.
 
+## Project rules
+
+A `rules.yml` beside `project.yml` writes down how a project's files are named, laid out
+and written, so everyone working on it, people and coding agents alike, keeps it the
+same:
+
+```yaml
+# rules.yml
+ids:
+  collections: kebab-case # or a pattern, such as '{folder}-[a-z0-9-]+'
+layout:
+  folders: required # every collection in a folder of collections/
+docs:
+  collections: required
+tags:
+  allowed: [smoke, regression]
+steps:
+  names: required
+tests:
+  only: [gta] # tests call the gta.* functions, and nothing else
+  statusCode: required
+guide: |
+  Name each step for what it proves.
+```
+
+```sh
+gta rules                        # the rules in effect, where each came from, what each means, the guide
+gta lint                         # check every file against them
+gta lint --json                  # the findings as JSON, for tools and agents
+```
+
+`gta lint` prints each finding at its file and line, with the rule it breaks, and exits
+`1` when it finds one. Rules never change a run: a file that breaks one still runs. A
+global project's `rules.yml` is shared like its `settings.yml`, and a project changes or
+turns off (`null`) any rule in its own file. Every rule is in
+[SPEC.md §1.4](https://github.com/schwabyio/gravity/blob/main/SPEC.md#14-rulesyml).
+
 ## In CI
 
 ```yaml
@@ -147,11 +184,151 @@ even an empty one.
   with:
     node-version: 22
 - run: npm install -g @schwabyio/gta
+- run: gta lint
 - run: gta all --environmentType staging --generateJUnitResults
   env:
     apiKey: ${{ secrets.STAGING_API_KEY }}
 ```
 
+## From Playwright and other code
+
+The package is also a library. A test written in code can run a collection or a request
+set, then use the values it saved, such as a token or the id of a user it created, in a
+browser test.
+
+### Playwright
+
+`@schwabyio/gta/playwright` gives you Playwright's `test` with a `gta` fixture. Point it
+at the project in `playwright.config.ts`:
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test'
+import type { GravityConfig } from '@schwabyio/gta/playwright'
+
+export default defineConfig<{}, GravityConfig>({
+  use: {
+    gravity: { project: '../api-tests', environment: 'staging' }
+  }
+})
+```
+
+```ts
+// tests/dashboard.spec.ts
+import { test, expect } from '@schwabyio/gta/playwright'
+
+test('a new user sees their dashboard', async ({ page, gta }) => {
+  // requests/create-user.yml, run as a use: step would run it
+  const user = await gta.use('create-user', { plan: 'pro' })
+
+  await page.goto(`/users/${user.values.userId}`)
+  await expect(page.getByRole('heading')).toHaveText('Welcome')
+
+  // collections/billing.yml, starting from what create-user saved
+  await gta.run('billing', { vars: user.values })
+})
+```
+
+- Each `gta.run` and `gta.use` call is a step in Playwright's report. Each request is a
+  step inside it, linked to its step in the YAML, with the request and response attached.
+- A run that fails fails the test at the line that called it, with what failed. With
+  `soft: true` the test goes on and fails at the end, as `expect.soft` does.
+- `project` is relative to the folder `playwright.config.ts` is in, and defaults to it.
+  `environment`, `flags`, `bail` and `timeoutCollection` go beside it. The project opens
+  once per worker, so an environment's flag command runs once per worker.
+- A run counts toward the test's timeout, and one still going when the test ends is
+  stopped.
+- To use this `test` with fixtures of your own, combine them with Playwright's
+  `mergeTests`.
+
+It needs `@playwright/test` 1.51 or later, which installing `gta` does not install.
+
+**When the project is in another repository**, check it out beside the app's and read
+its path from an environment variable, so a checkout anywhere else can say where it is:
+
+```ts
+// playwright.config.ts
+export default defineConfig<{}, GravityConfig>({
+  use: {
+    gravity: { project: process.env.GTA_PROJECT ?? '../api-tests' }
+  }
+})
+```
+
+`project` names the folder holding `collections/`. A project that `uses:` a global
+project needs the repository checked out whole, since the global project is found from
+it. In CI, check out both:
+
+```yaml
+# .github/workflows/e2e.yml (steps)
+- uses: actions/checkout@v4
+  with:
+    path: web
+- uses: actions/checkout@v4
+  with:
+    repository: your-org/api-tests
+    path: api-tests
+    token: ${{ secrets.API_TESTS_TOKEN }} # when that repository is private
+- uses: actions/setup-node@v4
+  with:
+    node-version: 22
+- run: npm ci && npx playwright install --with-deps
+  working-directory: web
+- run: npx playwright test
+  working-directory: web
+  env:
+    GTA_PROJECT: ${{ github.workspace }}/api-tests
+    apiKey: ${{ secrets.STAGING_API_KEY }}
+```
+
+### Any other code
+
+```js
+import { openProject } from '@schwabyio/gta'
+
+const project = await openProject('api-tests', { environment: 'staging' })
+const login = await project.use('login', { username: 'alice' })
+const checkout = await project.run('checkout', { vars: login.values })
+if (!checkout.passed) throw new Error(checkout.failures)
+```
+
+**`openProject(folder, options)`** opens the project in `folder`, the one holding
+`collections/`. The options are `environment`, `flags`, `bail` and `timeoutCollection`.
+Each one you leave out comes from `settings.yml`, the same way `gta` reads it, but here
+the project does not need a `settings.yml`.
+
+**`project.run(collection, options)`** runs a collection the way `gta` runs it: setup,
+then the steps once for each data row, then teardown. Name the collection by its id or
+its place in `collections/` (`checkout/sessions`). `tags` and `notTags` don't apply,
+since you name what runs, and a collection with `exclude: true` runs too. The options:
+
+| Option     | What it does                                                                                                                         |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `steps`    | Run only these steps, named as reports name them or numbered from 1. They run in the file's order, and setup and teardown still run. |
+| `vars`     | Values the run starts with. They sit over the environment and under a data row.                                                      |
+| `bail`     | Stop at the first failing step.                                                                                                      |
+| `signal`   | An `AbortSignal` that stops the run.                                                                                                 |
+| `onResult` | `(result, step) => void`, called as each request finishes.                                                                           |
+
+**`project.use(name, params, options)`** runs reusable requests as a `use:` step would:
+`login` is `requests/login.yml`, in the project or its global project. `params` are what
+`with:` gives, and a param you leave out takes its default. The options are those of
+`run`, without `steps`.
+
+Both resolve to the same outcome, however the steps fare:
+
+| Field      | What it holds                                                                                                                                                   |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `passed`   | `true` when nothing failed or errored and the run finished.                                                                                                     |
+| `values`   | Every value the run set or captured, by name: `gta.set`, and checks that save what they read, such as `'setAsCollectionVariable'`. Secrets are not hidden here. |
+| `summary`  | Totals, and every request's result as gta's JSON report holds it, with secrets shown as `[secret: NAME]`.                                                       |
+| `steps`    | Where each result's step is: its file and line.                                                                                                                 |
+| `failures` | What went wrong, as `gta` prints it under Failures. Empty when the run passed.                                                                                  |
+| `error`    | Why the run did not start or finish: a file that will not load, `timeoutCollection`, or a cancel. Otherwise `null`.                                             |
+
+They reject only when a collection, step or reusable requests file doesn't exist, or a
+value isn't a string, number, boolean or null. Types ship with the package.
+
 ## The file format
 
 [SPEC.md](https://github.com/schwabyio/gravity/blob/main/SPEC.md) specifies every file,

package/dist/FUNCTIONS.md

@@ -49,7 +49,7 @@ goes, the order it runs in, and the other globals: `res`, `req`, `assert`, `para
 ## How calls behave
 
 - **Every `tests` script of a step feeds one list of checks**: the collection's, the
-  step's, and those of an endpoint base, a base collection or a request set it runs
+  step's, and those of an endpoint base, a base collection or reusable requests it runs
   under (SPEC.md §2.5–§2.7). Strict validation counts them all together.
 - **A check that fails does not stop the script.** The checks after it still run, and
   the step fails.
@@ -216,8 +216,11 @@ gta.expectResponseBodyToHaveUnorderedArray('users', [{ name: 'Ada' }, { name: /^
 ```
 
 An object in the list matches an item holding each of its properties with that value, or
-matching it when the value is a `RegExp`. The item may have others. A pattern is tested
-against the value as text, so it never matches an item that is an object or an array.
+matching it when the value is a `RegExp`. The item may have others. A property that is
+itself an object is matched the same way, so `{ data: { status: 'reversed' } }` finds an
+item whose `data` has that status, whatever else `data` holds. An array compares whole.
+A pattern is tested against the value as text, so it never matches an item that is an
+object or an array.
 
 **A list of `{ pathToProperty, expectedValue, specialHandling? }` entries.** Together
 they describe **one** item, property by property, and some item must match every entry.