[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>
This commit is contained in:
Bertie690 2025-06-07 21:02:25 -04:00 committed by GitHub
parent 93745f14b7
commit 09e30070f9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 55 additions and 26 deletions

View File

@ -11,14 +11,24 @@ import { generateStarter } from "../gameManagerUtils";
import { GameManagerHelper } from "./gameManagerHelper"; import { GameManagerHelper } from "./gameManagerHelper";
/** /**
* Helper to handle classic mode specifics * Helper to handle classic-mode specific operations.
*/ */
export class ClassicModeHelper extends GameManagerHelper { export class ClassicModeHelper extends GameManagerHelper {
/** /**
* Runs the classic game to the summon phase. * 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. * @returns A promise that resolves when the summon phase is reached.
*/ */
async runToSummon(species: SpeciesId[]): Promise<void>;
/**
* 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<void>;
async runToSummon(species: SpeciesId[] | undefined): Promise<void>;
async runToSummon(species?: SpeciesId[]): Promise<void> { async runToSummon(species?: SpeciesId[]): Promise<void> {
await this.game.runToTitle(); await this.game.runToTitle();
@ -42,9 +52,18 @@ export class ClassicModeHelper extends GameManagerHelper {
/** /**
* Transitions to the start of a battle. * 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. * @returns A promise that resolves when the battle is started.
*/ */
async startBattle(species: SpeciesId[]): Promise<void>;
/**
* 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<void>;
async startBattle(species?: SpeciesId[]): Promise<void> { async startBattle(species?: SpeciesId[]): Promise<void> {
await this.runToSummon(species); await this.runToSummon(species);

View File

@ -20,9 +20,9 @@ export class FieldHelper extends GameManagerHelper {
* Passthrough for {@linkcode globalScene.getPlayerPokemon} that adds an `undefined` check for * 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`. * 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()!`. * 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` * @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} * @returns The first {@linkcode PlayerPokemon} that is {@linkcode globalScene.getPlayerField | on the field}
* and {@linkcode PlayerPokemon.isActive is active} * and {@linkcode PlayerPokemon.isActive | is active}
* (aka {@linkcode PlayerPokemon.isAllowedInBattle is allowed in battle}). * (aka {@linkcode PlayerPokemon.isAllowedInBattle is allowed in battle}).
*/ */
public getPlayerPokemon(includeSwitching = true): PlayerPokemon { 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`. * 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()!`. * 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` * @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} * @returns The first {@linkcode EnemyPokemon} that is {@linkcode globalScene.getEnemyField | on the field}
* and {@linkcode EnemyPokemon.isActive is active} * and {@linkcode EnemyPokemon.isActive | is active}
* (aka {@linkcode EnemyPokemon.isAllowedInBattle is allowed in battle}). * (aka {@linkcode EnemyPokemon.isAllowedInBattle | is allowed in battle}).
*/ */
public getEnemyPokemon(includeSwitching = true): EnemyPokemon { public getEnemyPokemon(includeSwitching = true): EnemyPokemon {
const pokemon = this.game.scene.getEnemyPokemon(includeSwitching); 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. * @returns The {@linkcode BattlerIndex | indexes} of Pokemon on the field in order of decreasing Speed.
* Speed ties are returned in increasing order of index. * 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[] { public getSpeedOrder(): BattlerIndex[] {
return this.game.scene 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 pokemon - The pokemon to mock the ability of
* @param ability - The ability to be mocked * @param ability - The ability to be mocked
* @returns A {@linkcode MockInstance} object * @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. * Force a given Pokemon to be terastallized to the given type.
*
* This function only mocks the Pokemon's tera-related variables; it does NOT activate any tera-related abilities.
* *
* @param pokemon - The pokemon to terastallize. * @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); vi.spyOn(pokemon, "isTerastallized", "get").mockReturnValue(true);
teraType ??= pokemon.getSpeciesForm(true).type1;
vi.spyOn(pokemon, "teraType", "get").mockReturnValue(teraType); vi.spyOn(pokemon, "teraType", "get").mockReturnValue(teraType);
} }
} }

View File

@ -154,7 +154,7 @@ export class MoveHelper extends GameManagerHelper {
* Changes a pokemon's moveset to the given move(s). * 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). * 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 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 { public changeMoveset(pokemon: Pokemon, moveset: MoveId | MoveId[]): void {
if (!Array.isArray(moveset)) { 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). * against the given target (if applicable).
* @param moveId The {@linkcode MoveId | move} the enemy will use * @param moveId - The {@linkcode Move | move ID} the enemy will be forced to use.
* @param target (Optional) the {@linkcode BattlerIndex | target} which the enemy will use the given move against * @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) { public async selectEnemyMove(moveId: MoveId, target?: BattlerIndex) {
// Wait for the next EnemyCommandPhase to start // 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. * 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) { public async forceEnemyMove(moveId: MoveId, target?: BattlerIndex) {
// Wait for the next EnemyCommandPhase to start // Wait for the next EnemyCommandPhase to start