From 09e30070f904c7993fa621a924fb057546591233 Mon Sep 17 00:00:00 2001 From: Bertie690 <136088738+Bertie690@users.noreply.github.com> Date: Sat, 7 Jun 2025 21:02:25 -0400 Subject: [PATCH] [Docs] Fixed test helper functions to conform with TSDoc standard; deprecated `runToSummon`/`startBattle` without args (#5912) * Updated doc comments for test-related functions * Marked `classicMode.runToSummon` and `classicMode.startBattle` without species as deprecated Having the species being used depend on daily run RNG is both unintuitive, janky and prone to flaking out (as happened with the Gastro Acid tests) * Fixed the bug * Update field-helper.ts Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com> --------- Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com> --- test/testUtils/helpers/classicModeHelper.ts | 25 ++++++++++++++--- test/testUtils/helpers/field-helper.ts | 30 +++++++++++---------- test/testUtils/helpers/moveHelper.ts | 26 +++++++++++------- 3 files changed, 55 insertions(+), 26 deletions(-) diff --git a/test/testUtils/helpers/classicModeHelper.ts b/test/testUtils/helpers/classicModeHelper.ts index 575000c2193..c4f086bd628 100644 --- a/test/testUtils/helpers/classicModeHelper.ts +++ b/test/testUtils/helpers/classicModeHelper.ts @@ -11,14 +11,24 @@ import { generateStarter } from "../gameManagerUtils"; import { GameManagerHelper } from "./gameManagerHelper"; /** - * Helper to handle classic mode specifics + * Helper to handle classic-mode specific operations. */ export class ClassicModeHelper extends GameManagerHelper { /** * Runs the classic game to the summon phase. - * @param species - Optional array of species to summon. + * @param species - An array of {@linkcode Species} to summon. * @returns A promise that resolves when the summon phase is reached. */ + async runToSummon(species: SpeciesId[]): Promise; + /** + * Runs the classic game to the summon phase. + * Selects 3 daily run starters with a fixed seed of "test" + * (see `DailyRunConfig.getDailyRunStarters` in `daily-run.ts` for more info). + * @returns A promise that resolves when the summon phase is reached. + * @deprecated - Specifying the starters helps prevent inconsistencies from internal RNG changes. + */ + async runToSummon(): Promise; + async runToSummon(species: SpeciesId[] | undefined): Promise; async runToSummon(species?: SpeciesId[]): Promise { await this.game.runToTitle(); @@ -42,9 +52,18 @@ export class ClassicModeHelper extends GameManagerHelper { /** * Transitions to the start of a battle. - * @param species - Optional array of species to start the battle with. + * @param species - An array of {@linkcode Species} to start the battle with. * @returns A promise that resolves when the battle is started. */ + async startBattle(species: SpeciesId[]): Promise; + /** + * Transitions to the start of a battle. + * Will select 3 daily run starters with a fixed seed of "test" + * (see `DailyRunConfig.getDailyRunStarters` in `daily-run.ts` for more info). + * @returns A promise that resolves when the battle is started. + * @deprecated - Specifying the starters helps prevent inconsistencies from internal RNG changes. + */ + async startBattle(): Promise; async startBattle(species?: SpeciesId[]): Promise { await this.runToSummon(species); diff --git a/test/testUtils/helpers/field-helper.ts b/test/testUtils/helpers/field-helper.ts index 08b7a210e68..aa01ef7497d 100644 --- a/test/testUtils/helpers/field-helper.ts +++ b/test/testUtils/helpers/field-helper.ts @@ -20,9 +20,9 @@ export class FieldHelper extends GameManagerHelper { * Passthrough for {@linkcode globalScene.getPlayerPokemon} that adds an `undefined` check for * the Pokemon so that the return type for the function doesn't have `undefined`. * This removes the need to add a `!` like when calling `game.scene.getPlayerPokemon()!`. - * @param includeSwitching Whether a pokemon that is currently switching out is valid, default `true` - * @returns The first {@linkcode PlayerPokemon} that is {@linkcode globalScene.getPlayerField on the field} - * and {@linkcode PlayerPokemon.isActive is active} + * @param includeSwitching - Whether a pokemon that is currently switching out is valid, default `true` + * @returns The first {@linkcode PlayerPokemon} that is {@linkcode globalScene.getPlayerField | on the field} + * and {@linkcode PlayerPokemon.isActive | is active} * (aka {@linkcode PlayerPokemon.isAllowedInBattle is allowed in battle}). */ public getPlayerPokemon(includeSwitching = true): PlayerPokemon { @@ -36,9 +36,9 @@ export class FieldHelper extends GameManagerHelper { * the Pokemon so that the return type for the function doesn't have `undefined`. * This removes the need to add a `!` like when calling `game.scene.getEnemyPokemon()!`. * @param includeSwitching Whether a pokemon that is currently switching out is valid, default `true` - * @returns The first {@linkcode EnemyPokemon} that is {@linkcode globalScene.getEnemyField on the field} - * and {@linkcode EnemyPokemon.isActive is active} - * (aka {@linkcode EnemyPokemon.isAllowedInBattle is allowed in battle}). + * @returns The first {@linkcode EnemyPokemon} that is {@linkcode globalScene.getEnemyField | on the field} + * and {@linkcode EnemyPokemon.isActive | is active} + * (aka {@linkcode EnemyPokemon.isAllowedInBattle | is allowed in battle}). */ public getEnemyPokemon(includeSwitching = true): EnemyPokemon { const pokemon = this.game.scene.getEnemyPokemon(includeSwitching); @@ -50,7 +50,9 @@ export class FieldHelper extends GameManagerHelper { * @returns The {@linkcode BattlerIndex | indexes} of Pokemon on the field in order of decreasing Speed. * Speed ties are returned in increasing order of index. * - * Note: Trick Room does not modify the speed of Pokemon on the field. + * @remarks + * This does not account for Trick Room as it does not modify the _speed_ of Pokemon on the field, + * only their turn order. */ public getSpeedOrder(): BattlerIndex[] { return this.game.scene @@ -60,7 +62,8 @@ export class FieldHelper extends GameManagerHelper { } /** - * Mocks a pokemon's ability, overriding its existing ability (takes precedence over global overrides) + * Mocks a pokemon's ability, overriding its existing ability (takes precedence over global overrides). + * Useful for giving exactly 1 Pokemon in a double battle a certain ability (rather than all pokemon). * @param pokemon - The pokemon to mock the ability of * @param ability - The ability to be mocked * @returns A {@linkcode MockInstance} object @@ -72,16 +75,15 @@ export class FieldHelper extends GameManagerHelper { } /** - * Forces a pokemon to be terastallized. Defaults to the pokemon's primary type if not specified. - * - * This function only mocks the Pokemon's tera-related variables; it does NOT activate any tera-related abilities. + * Force a given Pokemon to be terastallized to the given type. * * @param pokemon - The pokemon to terastallize. - * @param teraType - (optional) The {@linkcode PokemonType} to terastallize it as. + * @param teraType - The {@linkcode PokemonType} to terastallize into; defaults to the pokemon's primary type. + * @remarks + * This function only mocks the Pokemon's tera-related variables; it does NOT activate any tera-related abilities. */ - public forceTera(pokemon: Pokemon, teraType?: PokemonType): void { + public forceTera(pokemon: Pokemon, teraType: PokemonType = pokemon.getSpeciesForm(true).type1): void { vi.spyOn(pokemon, "isTerastallized", "get").mockReturnValue(true); - teraType ??= pokemon.getSpeciesForm(true).type1; vi.spyOn(pokemon, "teraType", "get").mockReturnValue(teraType); } } diff --git a/test/testUtils/helpers/moveHelper.ts b/test/testUtils/helpers/moveHelper.ts index 878a265ce84..c7dea05b095 100644 --- a/test/testUtils/helpers/moveHelper.ts +++ b/test/testUtils/helpers/moveHelper.ts @@ -154,7 +154,7 @@ export class MoveHelper extends GameManagerHelper { * Changes a pokemon's moveset to the given move(s). * Used when the normal moveset override can't be used (such as when it's necessary to check or update properties of the moveset). * @param pokemon - The {@linkcode Pokemon} being modified - * @param moveset - The {@linkcode MoveId} (single or array) to change the Pokemon's moveset to + * @param moveset - The {@linkcode MoveId} (single or array) to change the Pokemon's moveset to. */ public changeMoveset(pokemon: Pokemon, moveset: MoveId | MoveId[]): void { if (!Array.isArray(moveset)) { @@ -169,10 +169,14 @@ export class MoveHelper extends GameManagerHelper { } /** - * Forces the next enemy selecting a move to use the given move in its moveset + * Forces the next enemy selecting a move to use the given move _in its moveset_ * against the given target (if applicable). - * @param moveId The {@linkcode MoveId | move} the enemy will use - * @param target (Optional) the {@linkcode BattlerIndex | target} which the enemy will use the given move against + * @param moveId - The {@linkcode Move | move ID} the enemy will be forced to use. + * @param target - The {@linkcode BattlerIndex | target} against which the enemy will use the given move; + * defaults to normal target selection priorities if omitted or not single-target. + * @remarks + * If you do not need to check for changes in the enemy's moveset as part of the test, it may be + * best to use {@linkcode forceEnemyMove} instead. */ public async selectEnemyMove(moveId: MoveId, target?: BattlerIndex) { // Wait for the next EnemyCommandPhase to start @@ -200,14 +204,18 @@ export class MoveHelper extends GameManagerHelper { } /** - * Forces the next enemy selecting a move to use the given move against the given target (if applicable). + * Modify the moveset of the next enemy selecting a move to contain only the given move, and then + * selects it to be used during the next {@linkcode EnemyCommandPhase} against the given targets. * - * Warning: Overwrites the pokemon's moveset and disables the moveset override! + * Does not require the given move to be in the enemy's moveset beforehand, + * but **overwrites the pokemon's moveset** and **disables any prior moveset overrides**! * - * Note: If you need to check for changes in the enemy's moveset as part of the test, it may be + * @param moveId - The {@linkcode Move | move ID} the enemy will be forced to use. + * @param target - The {@linkcode BattlerIndex | target} against which the enemy will use the given move; + * defaults to normal target selection priorities if omitted or not single-target. + * @remarks + * If you need to check for changes in the enemy's moveset as part of the test, it may be * best to use {@linkcode changeMoveset} and {@linkcode selectEnemyMove} instead. - * @param moveId The {@linkcode MoveId | move} the enemy will use - * @param target (Optional) the {@linkcode BattlerIndex | target} which the enemy will use the given move against */ public async forceEnemyMove(moveId: MoveId, target?: BattlerIndex) { // Wait for the next EnemyCommandPhase to start