@substrio/cli 0.0.0-stage → 0.1.0

package/src/testing/env.mjs

@@ -0,0 +1,35 @@
+/**
+ * The contract between `substrio test` and the test files it runs: the server to
+ * use and the app to apply. The master key is never in the environment (a child
+ * process's environment is readable); it is in a 0600 file this names.
+ */
+
+import { TestError, TestErrorCode } from './types.mjs';
+
+/** The environment variables of the contract. */
+export const TestEnv = Object.freeze({
+    URL: 'SUBSTRIO_TEST_URL',
+    KEY_FILE: 'SUBSTRIO_TEST_KEY_FILE',
+    APP_DIR: 'SUBSTRIO_TEST_APP_DIR',
+});
+
+/** Reads the contract from `env`; a TestError outside `substrio test`. Returns {url, keyFile, appDir}. */
+export function readTestEnv(env = process.env) {
+    const missing = Object.values(TestEnv).filter((name) => !env[name]);
+    if (missing.length > 0) {
+        throw new TestError(`startApp() works under \`substrio test\`, which sets ${missing.join(', ')}; run this file with \`substrio test\``, TestErrorCode.NOT_UNDER_SUBSTRIO_TEST);
+    }
+    return { url: env[TestEnv.URL], keyFile: env[TestEnv.KEY_FILE], appDir: env[TestEnv.APP_DIR] };
+}
+
+/**
+ * Set by a node test runner in every process it starts. `substrio test` starts a run
+ * of its own, which with it inherited would skip every file as a nested run.
+ */
+const NODE_TEST_CONTEXT = 'NODE_TEST_CONTEXT';
+
+/** The environment a `substrio test` child gets: `base` without a parent run's context, plus the contract. */
+export function testEnvFor({ url, keyFile, appDir }, base = process.env) {
+    const { [NODE_TEST_CONTEXT]: _parentRun, ...own } = base;
+    return { ...own, [TestEnv.URL]: url, [TestEnv.KEY_FILE]: keyFile, [TestEnv.APP_DIR]: appDir };
+}

package/src/testing/index.mjs

@@ -0,0 +1,11 @@
+/**
+ * @substrio/cli/test: what a test file of an app imports.
+ *
+ *   import { startApp, fixture, Level } from '@substrio/cli/test';
+ *
+ * Run the files with `substrio test`.
+ */
+
+export { startApp, fixture, Fixture, TestApp, Run, FunctionRef, TestCollection, TestDb, TestLogs, FetchStubs, FetchCall, TestTenantClock } from './app.mjs';
+export { TestEnv } from './env.mjs';
+export { CallOutcome, ClockMode, HttpMethod, Level, PathMatch, RunOutcome, TestError, TestErrorCode, TriggerKind } from './types.mjs';

package/src/testing/types.mjs

@@ -0,0 +1,55 @@
+/**
+ * The closed sets of the test API (`@substrio/cli/test`) as frozen enums, and
+ * the typed error of a misused harness. Strings exist only on the wire; a test
+ * names a level, a method, a trigger kind by these.
+ */
+
+/** A function log line's level (function.logs). */
+export const Level = Object.freeze({
+    TRACE: 'trace', DEBUG: 'debug', INFO: 'info', WARN: 'warn', ERROR: 'error', FATAL: 'fatal',
+});
+
+/** How a call to a function ended. */
+export const RunOutcome = Object.freeze({ OK: 'ok', ERROR: 'error' });
+
+/** The change a collection trigger fires on. */
+export const TriggerKind = Object.freeze({ INSERT: 'insert', UPDATE: 'update', DELETE: 'delete' });
+
+/** A request method a stub answers or a test sends. */
+export const HttpMethod = Object.freeze({
+    GET: 'GET', POST: 'POST', PUT: 'PUT', DELETE: 'DELETE', PATCH: 'PATCH', OPTIONS: 'OPTIONS', HEAD: 'HEAD',
+});
+
+/** How a stub's path matches: the path alone, or it and everything below it. */
+export const PathMatch = Object.freeze({ EXACT: 'exact', PREFIX: 'prefix' });
+
+/** What became of a recorded fetch. */
+export const CallOutcome = Object.freeze({ STUBBED: 'stubbed', UNMATCHED: 'unmatched' });
+
+/** How a test tenant's clock runs. */
+export const ClockMode = Object.freeze({ REAL: 'real', FROZEN: 'frozen', OFFSET: 'offset' });
+
+/** What went wrong with the harness itself, not with the app under test. */
+export const TestErrorCode = Object.freeze({
+    NOT_UNDER_SUBSTRIO_TEST: 'NOT_UNDER_SUBSTRIO_TEST', // startApp outside `substrio test`
+    UNKNOWN_FUNCTION: 'UNKNOWN_FUNCTION',       // a name the app does not deploy
+    NO_SCHEDULE: 'NO_SCHEDULE',                 // cron() of a function with no [[cron]]
+    INVALID_FIXTURE: 'INVALID_FIXTURE',
+    INVALID_ARGUMENT: 'INVALID_ARGUMENT',       // a value outside its enum, a bad stub
+    TIMEOUT: 'TIMEOUT',
+    APP_FAILED: 'APP_FAILED',                   // the app could not be applied to the test tenant
+});
+
+export class TestError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = 'TestError';
+        this.code = code;
+    }
+}
+
+/** `value` when it is a member of the frozen enum `set`, else a typed TestError naming the members. */
+export function member(set, value, what) {
+    if (Object.values(set).includes(value)) return value;
+    throw new TestError(`${what} must be one of ${Object.values(set).join(', ')}, not ${JSON.stringify(value)}`, TestErrorCode.INVALID_ARGUMENT);
+}