@schwabyio/gta 0.10.0 → 0.11.0

package/README.md

@@ -108,14 +108,14 @@ The steps within a collection always run in order.
 
 The exit code is `0` when everything passed, `1` when something failed, and `2` when
 `gta` could not run at all, such as with a bad setting or an unknown collection.
-`gta get` exits `1` when a collection is broken, or has a `use:` or `extends:` a run
-would stop at.
+`gta get` exits `1` when a collection is broken, or has a `use:`, an `extends:` or a
+file its body sends that a run would stop at.
 
 ## Settings
 
 Settings come from `settings.yml`, then `GTA_*` environment variables, then flags on the
 command line, each overriding the one before. An unknown setting is an error.
-`gta --help` lists them all:
+`gta --help` lists them all, and `gta get` shows where each one came from:
 
 | Setting                  | Default        | What it does                                                   |
 | ------------------------ | -------------- | -------------------------------------------------------------- |
@@ -134,6 +134,11 @@ command line, each overriding the one before. An unknown setting is an error.
 The results folder is emptied before every run, so everything in it is from the last one.
 `gta` only ever deletes a folder that holds nothing but its own reports.
 
+In a monorepo, projects that share a global project (`uses:` in `project.yml`) share its
+`settings.yml` too. It comes before the project's own, so a project changes a shared
+setting by setting it again in its own file. Each project still needs a `settings.yml`,
+even an empty one.
+
 ## In CI
 
 ```yaml

package/dist/SPEC.md

@@ -152,16 +152,16 @@ tls:
 
 The file is optional, and so is every key in it. Any other key is an error.
 
-| Key      | Type                   | Default     | Meaning                                                            |
-| -------- | ---------------------- | ----------- | ------------------------------------------------------------------ |
-| `name`   | string                 | folder name | Display name.                                                      |
-| `uses`   | string (relative path) | none        | A global project whose variables and environments this one shares. |
-| `vars`   | map of plain values    | none        | Variables for every collection in the project (§4).                |
-| `tls.ca` | list of relative paths | none        | Certificate files that requests trust (below).                     |
+| Key      | Type                   | Default     | Meaning                                               |
+| -------- | ---------------------- | ----------- | ----------------------------------------------------- |
+| `name`   | string                 | folder name | Display name.                                         |
+| `uses`   | string (relative path) | none        | A global project whose files this one shares (below). |
+| `vars`   | map of plain values    | none        | Variables for every collection in the project (§4).   |
+| `tls.ca` | list of relative paths | none        | Certificate files that requests trust (below).        |
 
 **`uses`** names a **global project**: an ordinary project whose `project.yml`
-variables, `environments/`, `requests/`, `endpoints/`, `bases/` and `checks/` every
-project using it shares.
+variables, `environments/`, `requests/`, `endpoints/`, `bases/`, `checks/` and
+`settings.yml` every project using it shares.
 
 - It must be a relative path. An absolute path is refused, since it would only work on
   one machine. Write it with `/`; `\` reads the same.
@@ -170,6 +170,7 @@ project using it shares.
 - An environment in the global project merges under the project's environment of the
   same name, key by key, and the project's values win. An environment only the global
   project has is available too.
+- The global project's `settings.yml` lies under the project's the same way (§1.3).
 
 **`tls.ca`** lists certificate files that requests trust, for a server whose certificate
 a company or local CA signed, or a server's own self-signed certificate. A request
@@ -212,8 +213,9 @@ Projects are shared between macOS, Windows and Linux, and read the same on all t
   without an extension. A file with such a name, made on macOS or Linux, is reported.
 - Files should use LF line endings. Gravity writes LF, and can add a `.gitattributes`
   scoped to the project's own files so that git keeps them LF on every platform. The same
-  block keeps `files/` exactly as committed, so a body sends the same bytes everywhere. For
-  files a body sends from another folder, add a `-text` line of your own.
+  block keeps `files/` exactly as committed, so a body sends the same bytes everywhere. A
+  global project is a project too: its own block covers its `files/`. For files a body
+  sends from another folder, add a `-text` line of your own.
 - The process environment is read by exact name on every platform, although Windows
   itself ignores case (§4, §6).
 
@@ -257,9 +259,22 @@ The results folder is emptied before every run. `gta` refuses to empty one that
 files it did not write, or one that holds the project itself. Every report replaces
 each secret's value with `[secret: NAME]` (§6).
 
+**From the global project.** A global project (§1.1) can have a `settings.yml` too.
+Every project that `uses` it runs with those settings under its own: a key the
+project's file sets wins, and a key it leaves out comes from the global project's file.
+
+- There is no switch to turn this off. A project undoes a shared setting by setting it
+  in its own file, back to the default if need be: `environmentType: null`, `tags: []`.
+- A project still needs a `settings.yml` of its own, even an empty one. A global project
+  need not have one.
+- A relative `testResultsBasePath` is relative to the project being run, whichever file
+  set it.
+
 **Overrides.** Each setting can be overridden by an environment variable, then by a
 command-line flag: `GTA_LIMIT_CONCURRENCY=8`, then `--limitConcurrency 8`. A list is
-comma-separated: `--tags smoke,api`.
+comma-separated: `--tags smoke,api`. In all, from lowest to highest: the default, the
+global project's `settings.yml`, the project's, the environment variable, the flag.
+`gta get` lists each setting that is not a default, and where it came from.
 
 **Running.** `gta` runs from the project folder:
 
@@ -269,9 +284,11 @@ comma-separated: `--tags smoke,api`.
 | `gta all`             | Every collection, except those with `exclude: true` (§2.4). |
 | `gta smoke,checkout/` | The collections and directories named, in that order.       |
 
-`gta get` also reports each `use:` and `extends:` that would stop a run, in every
-collection, including those `gta all` leaves out (Appendix A). It exits `1` when it finds
-one, or a broken collection, and `0` otherwise.
+`gta get` also reports each `use:` and `extends:` that would stop a run, and each file a
+body names that is in neither the project nor its global project (§2.2), in every
+collection, including those `gta all` leaves out (Appendix A). A file path with
+`{{variables}}` is left to the run. It exits `1` when it finds one, or a broken
+collection, and `0` otherwise.
 
 A collection is named by its `id`, or by its place (`checkout/sessions`). A directory is
 named by its name, and `checkout/` names only the directory. `--flag name=value` sets a
@@ -487,13 +504,28 @@ the project the step belongs to. For a step of a request set, that is the set's
 project, which may be a global one. The path is the same wherever the collection sits
 inside `collections/`.
 
+A file that is not there is looked for in the global project (§1.1), as a request set
+or a base collection is, so projects can share one copy of a file. A project's own file
+of the same path wins. `global:` before the path reads only the global project's:
+
+```yaml
+body:
+  multipart:
+    avatar: { file: files/test-png.png } # the project's, else the global project's
+    terms: { file: global:files/terms.pdf } # the global project's only
+```
+
 - It must be a relative path, written with `/`. An absolute path is refused.
+- A path out of the project folder, such as `../other/files/a.png`, is read from where
+  it points, with no global project to fall back to. A `global:` path stays inside the
+  global project folder, and is an error in a project that uses none.
 - `{{variables}}` resolve in the path, so a data file row (§2.8) can choose the file.
 - A file is sent byte for byte. `{{…}}` inside it is not a variable.
 - A file that cannot be read stops the step before anything is sent, in its own `body`
-  phase, naming the file.
+  phase, naming the file and each place it was looked for.
 - Where a request is shown (results, reports, `req.body`), a file's bytes appear as
-  `‹file files/avatar.png, 1234 bytes›`.
+  `‹file files/avatar.png, 1234 bytes›`, and a global project's file as
+  `‹file global:files/terms.pdf, 5254 bytes›`, however the step named it.
 
 ### 2.3 `settings` and `headers`
 
@@ -610,8 +642,8 @@ steps:
 values. No variable can take the place of a `params.` name.
 
 A default may name variables and other params, as in
-`email: '{{params.accountId}}@example.com'`. Like a `with:` value, it is resolved once,
-when the set starts, so `accountId: '{{$uuid}}'` is one id wherever the set reads it.
+`email: '{{params.accountId}}@example.com'`. Like a `with:` value, it is resolved once
+for each use, so `accountId: '{{$uuid}}'` is one id wherever the set reads it.
 
 **A use step** holds only `use`, `with`, `name`, `tags`, `flags`, `docs` and `tests`. A
 method key, `headers`, `body`, `settings` or `before` on it is an error, and `with`
@@ -621,9 +653,11 @@ without `use` is an error too.
   global project. `use: auth/login` is one directory down. `use: global:login` looks
   only in the global project.
 - **`with:`** gives plain values; a param left out takes its default. A string may hold
-  `{{variables}}`, resolved when the set starts. A missing required value, a name the
-  set does not take, or a value or default that cannot be resolved stops the set's
-  steps before anything is sent.
+  `{{variables}}`, resolved as the set's first request starts, just after the
+  collection's `before.script` has run for it: a value that script sets for each step
+  (§4) reaches the set. A missing required value, a name the set does not take, or a
+  value or default that cannot be resolved stops the set's steps before anything is
+  sent.
 - **Running.** A use step runs each of the set's steps in turn, in the collection's
   variable scope, so what one sets the next can read, and so can the steps after the use
   step. Each request is reported as its own result. When the use step has a `name`,
@@ -632,7 +666,10 @@ without `use` is an error too.
 - **Layers.** Headers and settings: the collection's, under the set's, under each
   step's own. Scripts run collection, then set, then step: `before.script` before the
   request and `tests` after. The use step's own `tests` run last, on the response of
-  the set's step marked `useTests: true`, or else its last step.
+  the set's step marked `useTests: true`, or else its last step. `params` is the set's
+  alone: the collection's scripts, and a base collection's or an endpoint's (§2.6,
+  §2.7), never see it. In an endpoint's `before.script`, a segment written as
+  `{{params.id}}` reads as written.
 - **One level.** A request set must not `use:` another, and has `params`, not `vars`. A
   file in `requests/` without `params` is not a request set.
 
@@ -1148,6 +1185,10 @@ There is nothing to load, and no `startXTest` or `endXTest`.
 | `gta.randomInt(min, max)`: a whole number, both ends included                                    |         ✓          |
 | `gta.date(format, secondsOffset = 0, timeZone = 'local')`                                        |         ✓          |
 
+`gta.set` keeps a string, number, boolean or null as it is, and stores an object or array
+as JSON text. `undefined` is stored as `null`, so a variable set to nothing still reads
+`== null`, and `{{name}}` resolves as a null does (§4).
+
 Calling a response check in `before.script` is an error, and so is `gta.skip` in
 `tests`, where the request has been sent. After `gta.skip` the script runs to its end,
 and no later `before.script` runs. `gta.skipRest` skips steps of this row only: the next
@@ -1372,8 +1413,8 @@ it. Rules checked at run time fail the step, or the run, before anything is sent
 - `uses` and `tls.ca` entries are relative paths.
 - The folder `uses` names has a `project.yml`, and does not itself `uses` another.
 - Each `tls.ca` file exists and holds a PEM or DER certificate.
-- `settings.yml` exists for `gta`, and its `environmentType`, if set, names an
-  environment that exists.
+- `settings.yml` exists for `gta`; a global project's is optional. The `environmentType`
+  a run ends up with, if any, names an environment that exists.
 
 **At run time**
 
@@ -1382,9 +1423,11 @@ it. Rules checked at run time fail the step, or the run, before anything is sent
 - Every feature flag named is known to the run.
 - The flag `command`, if any, has every quote closed, starts, and exits `0` within 60
   seconds, printing a JSON object.
-- Every file a body names can be read from the project folder.
+- Every file a body names can be read from the project folder, or its global
+  project's (§2.2).
 - Every `use:` and `extends:` names a usable file, and every `with:` suits its set.
-  `gta get` checks these without running anything (§1.3).
+  `gta get` checks these, and the body files named without `{{variables}}`, without
+  running anything (§1.3).
 - A step's `forEach` resolves to a JSON array.
 - In `{{@name}}`, `name` holds text naming a variable that exists.
 - A `before.script` sets `req.body` to text, and only for a `json`, `xml`, `text` or