@ibgib/ibgib/src/respec-gib-types.node.mts

ibgib RCLI (Robbotic/Request/Command Line Interface) front end :under_construction:

/**
 * @module respec-gib-types.node
 *
 * these started as B2tFS specific, but I am using them more generally with
 * non-B2tFS commands now.
 */

/**
 * from which type of repo do we want to test
 */
export type TestRepoType = 'simple' | 'complex';
/**
 * settings for test frameworks that deal with copying repo/ibgib folders to
 * initialize a context for testing ibgib cli commands (i.e. cmd handlers and
 * their side effects).
 */
export interface TestConfig {
    /**
     * base path of the test
     */
    basePath: string;
    /**
     * info that specifies the repo+.ibgib folder combination.
     */
    startState: {
        /**
         * path under `basePath` that contains .ibgib folder start states of the
         * ibgib data.
         *
         * atow (01/2024) the full path to here is `test-b2tfs/ibgib-folders` with
         * an example ibgib folder path being
         * `test-b2tfs/ibgib-folders/10_initialized`. this would be for an .ibgib
         * folder that has had the `ibgib --init` command executed only. (i.e. it
         * hasn't had other repl sessions or anything else that would grow the
         * contents of the .ibgib folder).
         *
         * ## notes
         *
         * when you are interacting with the ibgib rcli app, you are creating ibgibs
         * that are stored in ibgib spaces. all of this data lives in the .ibgib
         * folder (by default). this is the base subpath for snapshots of those
         * folder states for use in testing.
         *
         * atow (01/2024) i have this as 'ibgib-folders' under 'test-b2tfs'. so you
         * can look at these folders to grok what this is.
         */
        ibgibSnapshotsSubpath: string;
        /**
         * paths under base dir that point to the repo, depending on the complexity
         * of the example/test repo.
         */
        repoSubpaths: {
            /**
             * subpath that contains simple/contrived repos for very basic b2tfs
             * testing.
             */
            simple: string;
            /**
             * subpath that contains more complex repos for more advanced "real
             * world"-ish b2tfs testing.
             */
            complex: string;
        };
    };
    /**
     * output working directory that we copy test start state (ibgib and repo
     * folders). each unit/integration test (respecfully or ifWe block) should have
     * its own terse subfolder directly underneath this directory.
     *
     * NOTE: this is as short as possible because path lengths make a difference
     * with storage of ibgibs. (limitations of OS's)
     */
    outputSubPath: string;
    /**
     * filename of a temporary secret file used for testing.
     *
     * ## driving use caes
     *
     * i need to create a secret (--secret --add) and populate the --input-path=
     * field for the secret.
     */
    testPasswordFilename: string;
}

/**
 * a test start state combines a repo path with an ibgib path. this
 * provides permutations of start state for tests. this state will be
 * copied to a target test folder and then the test will begin with that
 * state.
 *
 * this allows composition of tests with repos of varying complexity and
 * ibgib data in varying states of progress.
 *
 * ## example
 *
 * so say you have a test repo with a single file 'readme.md'.  you would
 * normally nav to your repo folder and execute an init on the ibgib rcli
 * app itself. after this init, you would have an ibgib folder (.ibgib by
 * default) that contains the ibgib data.  we can snapshot this ibgib folder
 * at this point for testing.
 *
 * if we then do some other operations, like a successful b2tfs-init, in
 * which case the user has entered the name of the space, app, robbot, etc.
 * we can then snapshot this ibgib folder. we can then execute some tests on
 * this state, by again, copying the repo path and the ibgib folder to a new
 * folder and executing some test there.
 */
export interface TestStartState {
    /**
     * timeout specific to this start state.
     */
    timeoutMs: number;
    /**
     * used to generate the state of the .ibgibs folder for the b2tfs test case.
     */
    ibgibs: {
        /**
         * this name is used to subpath from the {@link TestConfig.startState.ibgibSnapshotsSubpath}
         */
        name: string;
    };
    /**
     * used to generate the state of the repo for the b2tfs test case.
     */
    repo: {
        /**
         * determines which repo subpath to look for in * {@link TestConfig.startState.repoSubpaths}
         */
        type: TestRepoType;
        /**
         * determines the name of the subfolder of the repo to use in the b2tfs test case
         */
        name: string;
    };
    /**
     * @optional description of the start state
     */
    description?: string;
}

/**
 * @see {@link FnAfterExecCmd}
 */
export interface FnAfterExecCmdArg {
    /**
     * this is the maam or sir or whatever from the caller's respec file.
     */
    respecfulTitle: string;
    std_out?: string;
    std_err?: string;
    err?: any | null;
    stdOutIncludes?: string[];
    fnlogalot?: boolean | number;
}
/**
 * this function should execute after the node cmd line one-off executes and
 * returns.
 *
 * this is expected to execute within an `ifWe` block, so you should be able to
 * use `iReckon` statements within this fn (e.g. as done atow (01/2024) in
 * {@link FN_DEFAULT_AFTER_EXEC_CMD}).
 *
 * @see {@link FnAfterExecCmdArg}
 * @see {@link FN_DEFAULT_AFTER_EXEC_CMD}
 */
export type FnAfterExecCmd = (arg: FnAfterExecCmdArg) => Promise<void>;