feat: introduce experimental reported tasks

[sheremet-va]

Description

This PR introduces a new way to work with the runner tasks on the server by implementing TestCase, TestSuite, and TestFile interfaces.

These values will be passed down to the new reporter interface. I am opening a draft to discuss the direction of this API.

The goal of this API is to provide a public interface that has an easy to understand methods and properties. It should also have useful method to travers and filter tests. The API should be documented with JSDocs commends and have a section in the advanced reporter guide.

onFinished(tests) {
  // to get the reported task, use `state.getReportedEntity` for now 
  // in the future, it will be passed down to the reporter
  const testFile = this.ctx.state.getReportedEntity(tests[0]) as TestFile
  const filePath = testFile.moduleId
  console.log('tests in, filePath, 'finished running')

  // iterate over all top level tests and suites in the file
  for (const task of testFile.children) {
    console.log(task.type, task.fullName)
  }

  // iterate over all tests in the file
  for (const test of testFile.children.allTests()) {
    console.log('test', test.fullName, test.result()?.state || 'running')
  }
  // iterate over only top level failed tests
  for (const test of testFile.children.tests('failed')) {
    console.log('test failed with errors', ...test.result()?.errors)
  }

  const myTest = testFile.children.at(0)!
  const duration = myTest.diagnostic()?.duration
  const myCustomMeta = myTest.meta().myCustomProperty
  if (myCustomMeta === 'success') {
    cosnole.log(myTest.fullName, 'did the thing')
  }
}

declare class TestTask {
    readonly project: TestProject;
    /**
     * Direct reference to the test file where the test is defined.
     */
    readonly file: TestFile;
    /**
     * Name of the test or the suite.
     */
    readonly name: string;
    /**
     * Full name of the test or the suite including all parent suites separated with `>`.
     */
    readonly fullName: string;
    /**
     * Unique identifier.
     * This ID is deterministic and will be the same for the same test across multiple runs.
     * The ID is based on the file path and test position.
     */
    readonly id: string;
    /**
     * Location in the file where the test or suite was defined.
     * Locations are collected only if `includeTaskLocation` is enabled in the config.
     */
    readonly location: {
        line: number;
        column: number;
    } | undefined;
}

declare class TestCase extends TestTask {
    /**
     * Task instance.
     * @experimental Public task API is experimental and does not follow semver.
     */
    readonly task: Test | Custom;
    readonly type = "test" | "custom";
    /**
     * Custom metadata that was attached to the test during its execution.
     */
    meta(): TaskMeta;
    /**
     * Parent suite of the test. If test was called directly inside the file, the parent will be the file.
     */
    readonly parent: TestSuite | TestFile;
    /**
     * Options that test was initiated with.
     */
    readonly options: TaskOptions;
    /**
     * Result of the test. Will be `undefined` if test is not finished yet or was just collected.
     */
    result(): TestResult | undefined
    /**
     * Useful information about the test like duration, memory usage, etc.
     */
    diagnostic(): TestDiagnostic | undefined;
}


declare class TestCollection {
    /**
     * Test or a suite at a specific index in the array.
     */
    at(index: number): TestCase | TestSuite | undefined
    /**
     * The number of tests and suites in the collection.
     */
    size: number
    /**
     * The same collection, but in an array form for easier manipulation.
     */
    array(): (TestCase | TestSuite)[];
    /**
     * Iterates over all tests and suites in the collection.
     */
    values(): IterableIterator<TestCase | TestSuite>;
    /**
     * Returns all suites that are part of this suite and its children.
     */
    allSuites(): IterableIterator<TestSuite>;
    /**
     * Returns all tests that are part of this suite and its children.
     */
    allTests(state?: TestResult['state'] | 'running'): IterableIterator<TestCase>;
    /**
     * Returns only tests that are part of this suite.
     */
    tests(state?: TestResult['state'] | 'running'): IterableIterator<TestCase>;
    /**
     * Returns only suites that are part of this suite.
     */
    suites(): IterableIterator<TestSuite>;
    [Symbol.iterator](): IterableIterator<TestSuite | TestCase>;
}

declare class TestSuite extends TestTask {
    /**
     * Task instance.
     * @experimental Public task API is experimental and does not follow semver.
     */
    readonly task: Suite;
    readonly type = "suite";
    /**
     * Parent suite. If suite was called directly inside the file, the parent will be the file.
     */
    readonly parent: TestSuite | TestFile;
    /**
     * Collection of suites and tests that are part of this suite.
     */
    readonly children: TaskCollection;
    /**
     * Options that the suite was initiated with.
     */
    readonly options: TaskOptions;
}
declare class TestFile extends TestTask {
    /**
     * Task instance.
     * @experimental Public task API is experimental and does not follow semver.
     */
    readonly task: File;
    readonly type = "file";
    /**
     * Collection of suites and tests that are part of this suite.
     */
    readonly children: TaskCollection;
    /**
     * This is usually an absolute UNIX file path.
     * It can be a virtual id if the file is not on the disk.
     * This value corresponds to Vite's `ModuleGraph` id.
     */
    readonly moduleId: string;
    readonly location: undefined;
}

declare class TestProject {
    /**
     * The global vitest instance.
     * @experimental The public Vitest API is experimental and does not follow semver.
     */
    readonly vitest: Vitest;
    /**
     * The workspace project this test project is associated with.
     * @experimental The public Vitest API is experimental and does not follow semver.
     */
    readonly workspaceProject: WorkspaceProject;
    /**
     * Resolved project configuration.
     */
    readonly config: ResolvedProjectConfig;
    /**
     * Resolved global configuration. If there are no workspace projects, this will be the same as `config`.
     */
    readonly globalConfig: ResolvedConfig;
    /**
     * Serialized project configuration. This is the config that tests receive.
     */
    get serializedConfig(): SerializedConfig;
    /**
     * The name of the project or an empty string if not set.
     */
    name(): string;
    /**
     * Custom context provided to the project.
     */
    context(): ProvidedContext;
    /**
     * Provide a custom context to the project. This context will be available for tests once they run.
     */
    provide<T extends keyof ProvidedContext & string>(key: T, value: ProvidedContext[T]): void;
}

interface TaskOptions {
    each: boolean | undefined;
    concurrent: boolean | undefined;
    shuffle: boolean | undefined;
    retry: number | undefined;
    repeats: number | undefined;
    mode: 'run' | 'only' | 'skip' | 'todo';
}
interface TestDiagnostic {
    heap: number | undefined;
    duration: number;
    startTime: number;
    retryCount: number;
    repeatCount: number;
    flaky: boolean
}

interface SerialisedError {
  message: string
  stack: string
  name: string
  stacks?: ParsedStack[]
  [key: string]: unknown
}

interface TestError extends SerialisedError {
  diff?: string
  actual?: string
  expected?: string
}

interface TestResult {
  state: 'passed' | 'failed' | 'skipped'
  errors?: TestError[]
}