@salesforce/agents/lib/agentTest.d.ts

Client side APIs for working with Salesforce agents

import { Connection } from '@salesforce/core';
import { DeployResult } from '@salesforce/source-deploy-retrieve';
import { AvailableDefinition, AgentTestConfig, AiEvaluationDefinition, AiTestingDefinition, TestSpec, NgtTestSpec } from './types.js';
import { TestRunnerType } from './utils';
/**
 * Events emitted during agent test creation for consumers to listen to and keep track of progress.
 */
export declare const AgentTestCreateLifecycleStages: {
    CreatingLocalMetadata: string;
    Waiting: string;
    DeployingMetadata: string;
    Done: string;
};
/**
 * A client side representation of an agent test (AiEvaluationDefinition) within an org.
 * Also provides utilities such as creating and listing agent tests, and converting between
 * agent test spec and AiEvaluationDefinition.
 *
 * **Examples**
 *
 * Create a new instance from an agent test spec:
 *
 * `const agentTest = new AgentTest({ specPath: path/to/specfile });`
 *
 * Get the metadata content of an agent test:
 *
 * `const metadataContent = await agentTest.getMetadata();`
 *
 * Write the metadata content to a file:
 *
 * `await agentTest.writeMetadata('path/to/metadataFile');`
 */
export declare class AgentTest {
    private config;
    private specData?;
    private data?;
    /**
     * Create an AgentTest based on one of:
     *
     * 1. AiEvaluationDefinition API name.
     * 2. Path to a local AiEvaluationDefinition metadata file.
     * 3. Path to a local agent test spec file.
     * 4. Agent test spec data.
     *
     * @param config AgentTestConfig
     */
    constructor(config: AgentTestConfig);
    /**
     * List the AiEvaluationDefinitions and AiTestingDefinitions metadata in the org.
     */
    static list(connection: Connection): Promise<AvailableDefinition[]>;
    /**
     * Creates and deploys a test definition from a specification file.
     *
     * Two metadata types are supported, selected via `options.testRunner`:
     * `'testing-center'` (default) — legacy `AiEvaluationDefinition`. Filename `<apiName>.aiEvaluationDefinition-meta.xml`.
     * `'agentforce-studio'` — new `AiTestingDefinition` (NGT). Filename `<apiName>.aiTestingDefinition-meta.xml`.
     * Requires Metadata API v66.0 or later on the target org; the server gates this and the lib does not preflight.
     *
     * @param connection - Connection to the org where the agent test will be created.
     * @param apiName - The API name of the test definition to create.
     * @param specFilePath - The path to the YAML specification file.
     * @param options - Configuration options for creating the definition.
     * @param options.outputDir - The directory where the metadata file will be written.
     * @param options.preview - If true, writes the metadata file to `<apiName>-preview-<timestamp>.xml` in the current working directory and does not deploy.
     * @param options.testRunner - Which test runner to author for. Defaults to `'testing-center'`.
     *
     * @returns Promise containing:
     * - path: The filesystem path to the created metadata file.
     * - contents: The metadata XML as a string.
     * - deployResult: The deployment result (if not in preview mode).
     *
     * @throws {SfError} When validation or deployment fails.
     */
    static create(connection: Connection, apiName: string, specFilePath: string, options: {
        outputDir: string;
        preview?: boolean;
        testRunner?: TestRunnerType;
    }): Promise<{
        path: string;
        contents: string;
        deployResult?: DeployResult;
    }>;
    /**
     * Get the specification for this agent test.
     *
     * Returns the test spec data if already generated. Otherwise it will generate the spec by:
     *
     * 1. Read from an existing local spec file.
     * 2. Read from an existing local metadata file and convert it. Dispatches on root XML element:
     * `<AiEvaluationDefinition>` → legacy `TestSpec`, `<AiTestingDefinition>` → `NgtTestSpec`.
     * 3. Use the provided org connection to read the remote metadata. Both metadata types are queried;
     * if both exist for the given name, throws `ambiguousTestDefinition`.
     *
     * @param connection Org connection to use if this AgentTest only has an API name.
     * @returns Promise<TestSpec | NgtTestSpec>
     */
    getTestSpec(connection?: Connection): Promise<TestSpec | NgtTestSpec>;
    /**
     * Get the metadata content for this agent test.
     *
     * Returns the AiEvaluationDefinition metadata if already generated. Otherwise it will get it by:
     *
     * 1. Read from an existing local AiEvaluationDefinition metadata file.
     * 2. Read from an existing local spec file and convert it.
     * 3. Use the provided org connection to read the remote AiEvaluationDefinition metadata.
     *
     * @param connection Org connection to use if this AgentTest only has an AiEvaluationDefinition API name.
     * @returns Promise<TestSpec>
     */
    getMetadata(connection?: Connection): Promise<AiEvaluationDefinition>;
    /**
     * Write a test specification file in YAML format.
     *
     * @param outputFile The file path where the YAML test spec should be written.
     */
    writeTestSpec(outputFile: string): Promise<void>;
    /**
     * Write AiEvaluationDefinition metadata file.
     *
     * @param outputFile The file path where the metadata file should be written.
     */
    writeMetadata(outputFile: string): Promise<void>;
}
/**
 * Validate an NGT test spec before conversion.
 *
 * Throws on the first failure encountered so authors get one clear actionable
 * error at a time. Emits a Lifecycle warning (does not throw) for unknown
 * scorer names — Core's MD validator catches those at deploy time.
 */
export declare const validateNgtSpec: (spec: NgtTestSpec, ctx: {
    isMultiAgent: boolean;
}) => void;
/**
 * Convert a validated `NgtTestSpec` to the `AiTestingDefinition` shape ready for XML serialization.
 *
 * Multi-input fan-out: when a test case has N inputs, emit N `<testCase>` elements sharing the
 * same scorer set. The `<number>` field increments globally across the whole document.
 *
 * Must be called after `validateNgtSpec`.
 */
export declare const convertToTestingMetadata: (spec: NgtTestSpec) => AiTestingDefinition;
/** Serialize an `AiTestingDefinition` to source-format XML. Mirrors `buildMetadataXml`. */
export declare const buildTestingMetadataXml: (data: AiTestingDefinition) => string;
/**
 * Parse an `AiTestingDefinition` source-format XML string into the `AiTestingDefinition`
 * metadata object. Mirror of {@link parseAgentTestXmlString} for the NGT runner.
 *
 * Throws SfError on malformed XML or on a missing/wrong root element. Use
 * {@link convertToNgtSpec} to convert the result into an `NgtTestSpec`.
 */
export declare const parseNgtMetadataXml: (xml: string) => AiTestingDefinition;
/**
 * Convert an `AiTestingDefinition` (parsed XML object form) back into an `NgtTestSpec`.
 * Inverse of {@link convertToTestingMetadata}; collapses contiguous test cases that share
 * an identical scorer set into a single multi-input case.
 */
export declare const convertToNgtSpec: (data: AiTestingDefinition) => NgtTestSpec;