chapterjs 0.2.3 → 0.3.0

package/dist/testing/index.d.ts

@@ -0,0 +1,4 @@
+export { scenario } from './scenario.js';
+export type { ScenarioDeclaration } from './scenario.js';
+export { TestFailure } from './failure.js';
+export type { ButtonTarget, FieldInputsOf, FormTarget, OptionInputsOf, SelectInput, SelectTarget, TestAssertions, TestBot, TestButton, TestChannel, TestChannelOptions, TestChannelType, TestFile, TestForm, TestMember, TestMemberOptions, TestMenu, TestMessage, TestReply, TestRole, TestRoleOptions, TestSuggestion, TestWhere, } from './harness.js';

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+// What `import ... from 'chapterjs/test'` gives: how a test of the bot is
+// written. The bot under test, the people and channels of its server and
+// what it answers are typed here; `chapterjs test` runs the scenarios.
+export { scenario } from './scenario.js';
+export { TestFailure } from './failure.js';

package/dist/testing/scenario.d.ts

@@ -0,0 +1,39 @@
+import type { Declaration } from '../loader/loader.js';
+import type { TestBot } from './harness.js';
+/** What a file gives to `scenario()`. */
+export interface ScenarioDeclaration {
+    /** What the file gave to `scenario()`, not checked yet. */
+    readonly config: {
+        label: string;
+        run: (bot: TestBot) => unknown;
+    };
+}
+/** A scenario, checked: what the runner works with. */
+export interface LoadedScenario {
+    readonly label: string;
+    readonly run: (bot: TestBot) => unknown;
+}
+/**
+ * Declares a test of your bot. Export the result from a `*.test.ts` file of
+ * `src/`: `chapterjs test` runs it against a Discord in memory, where the
+ * bot is in a server with a few people in it.
+ *
+ * ```ts
+ * import { scenario } from 'chapterjs/test';
+ * import { ping } from './ping';
+ *
+ * export default scenario('ping answers Pong', async bot => {
+ *   const reply = await bot.use(ping);
+ *   reply.says('Pong');
+ * });
+ * ```
+ *
+ * `bot` is the bot in its test server: `bot.use()` runs a command,
+ * `bot.click()` presses a button, `bot.say()` sends a message as someone,
+ * and what comes back says what the bot answered.
+ */
+export declare function scenario(label: string, run: (bot: TestBot) => unknown): ScenarioDeclaration;
+/** Whether a value was made by `scenario()`. */
+export declare function isScenarioDeclaration(value: unknown): value is ScenarioDeclaration;
+/** The `Declaration` of scenarios, for the loader. */
+export declare const scenarioDeclaration: Declaration<LoadedScenario>;

package/dist/testing/scenario.js

@@ -0,0 +1,58 @@
+// What a file of `src/` declares with `scenario()`: a test of the bot,
+// written by the developer, that `chapterjs test` runs against a Discord
+// in memory. A scenario names itself by its label, since that is what the
+// report shows: a file may export several, in a list too.
+const BRAND = Symbol.for('chapterjs.scenario');
+/**
+ * Declares a test of your bot. Export the result from a `*.test.ts` file of
+ * `src/`: `chapterjs test` runs it against a Discord in memory, where the
+ * bot is in a server with a few people in it.
+ *
+ * ```ts
+ * import { scenario } from 'chapterjs/test';
+ * import { ping } from './ping';
+ *
+ * export default scenario('ping answers Pong', async bot => {
+ *   const reply = await bot.use(ping);
+ *   reply.says('Pong');
+ * });
+ * ```
+ *
+ * `bot` is the bot in its test server: `bot.use()` runs a command,
+ * `bot.click()` presses a button, `bot.say()` sends a message as someone,
+ * and what comes back says what the bot answered.
+ */
+export function scenario(label, run) {
+    return Object.freeze({ [BRAND]: true, config: { label, run } });
+}
+/** Whether a value was made by `scenario()`. */
+export function isScenarioDeclaration(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[BRAND] === true);
+}
+const fail = (message) => {
+    throw new TypeError(message);
+};
+/** The longest label shown on one line of the report. */
+const MAX_LABEL = 120;
+/** The `Declaration` of scenarios, for the loader. */
+export const scenarioDeclaration = {
+    one: 'scenario',
+    many: 'scenarios',
+    is: isScenarioDeclaration,
+    list: true,
+    read(value) {
+        const { config } = value;
+        if (typeof config.label !== 'string' || config.label.trim() === '') {
+            fail(`scenario() needs a label first, what the test checks: scenario('ping answers Pong', async bot => { ... }).`);
+        }
+        if (config.label.length > MAX_LABEL) {
+            fail(`The label of this scenario is ${config.label.length} characters long: keep it under ${MAX_LABEL}, it is a title.`);
+        }
+        if (typeof config.run !== 'function') {
+            fail(`scenario('${config.label}') needs a function after its label, what the test does: async bot => { ... }.`);
+        }
+        return Object.freeze({ label: config.label.trim(), run: config.run });
+    },
+};

package/dist/testing/smoke.d.ts

@@ -0,0 +1,20 @@
+import type { Project } from '../cli/project.js';
+import type { Session } from './harness.js';
+/** One thing to check, with the cases it is checked in. */
+export interface Check {
+    /** What is checked: `command /ping`, `button confirm()`, `event memberJoin`... */
+    subject: string;
+    /** The file it comes from. */
+    file: string;
+    cases: Case[];
+}
+export interface Case {
+    /** How this case differs: `with everything`, `with reason at its longest`... */
+    label: string;
+    run(session: Session): Promise<void>;
+}
+/** Every check of the project, in the order of the report. */
+export declare function smokeChecks(project: Project): {
+    checks: Check[];
+    notSimulated: string[];
+};