feat: device.settings.apply with animations toggle (#287)

Author: gmegidish

cli/device.go

@@ -130,6 +130,37 @@ var deviceShutdownCmd = &cobra.Command{
 	},
 }
 
+var settingsCmd = &cobra.Command{
+	Use:   "settings",
+	Short: "Device settings commands",
+	Long:  `Commands for applying device-level settings such as animations.`,
+}
+
+var settingsAnimations string
+
+var settingsApplyCmd = &cobra.Command{
+	Use:   "apply",
+	Short: "Apply device settings",
+	Long:  `Apply device-level settings. Example: mobilecli device settings apply --animations=off`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		req := commands.ApplySettingsRequest{
+			DeviceID: deviceId,
+		}
+
+		if cmd.Flags().Changed("animations") {
+			req.Animations = &settingsAnimations
+		}
+
+		response := commands.ApplySettingsCommand(req)
+		printJson(response)
+		if response.Status == "error" {
+			return fmt.Errorf("%s", response.Error)
+		}
+
+		return nil
+	},
+}
+
 func init() {
 	rootCmd.AddCommand(deviceCmd)
 
@@ -139,16 +170,22 @@ func init() {
 	deviceCmd.AddCommand(deviceBootCmd)
 	deviceCmd.AddCommand(deviceShutdownCmd)
 	deviceCmd.AddCommand(orientationCmd)
+	deviceCmd.AddCommand(settingsCmd)
 
 	// add orientation subcommands
 	orientationCmd.AddCommand(orientationGetCmd)
 	orientationCmd.AddCommand(orientationSetCmd)
 
+	// add settings subcommands
+	settingsCmd.AddCommand(settingsApplyCmd)
+
 	// device command flags
 	deviceRebootCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to reboot")
 	deviceInfoCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to get info from")
 	deviceBootCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to boot")
 	deviceShutdownCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to shutdown")
 	orientationGetCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to get orientation from")
 	orientationSetCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to set orientation on")
+	settingsApplyCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to apply settings to")
+	settingsApplyCmd.Flags().StringVar(&settingsAnimations, "animations", "", "Toggle system animations: 'on' or 'off'")
 }

commands/settings.go

@@ -0,0 +1,53 @@
+package commands
+
+import (
+	"fmt"
+
+	"github.com/mobile-next/mobilecli/devices"
+	"github.com/mobile-next/mobilecli/utils"
+)
+
+// ApplySettingsRequest applies device-level settings to a device. Pointer
+// fields distinguish "not provided" from a zero value, so only the settings
+// explicitly set are touched (PATCH semantics).
+type ApplySettingsRequest struct {
+	DeviceID   string  `json:"deviceId"`
+	Animations *string `json:"animations,omitempty"` // "on" or "off"
+}
+
+// ApplySettingsCommand applies the provided device settings. Settings that a
+// platform cannot honor are skipped with a debug log and never fail the call.
+func ApplySettingsCommand(req ApplySettingsRequest) *CommandResponse {
+	device, err := FindDeviceOrAutoSelect(req.DeviceID)
+	if err != nil {
+		return NewErrorResponse(err)
+	}
+
+	if req.Animations != nil {
+		err = applyAnimations(device, *req.Animations)
+		if err != nil {
+			return NewErrorResponse(err)
+		}
+	}
+
+	return NewSuccessResponse(OK)
+}
+
+func applyAnimations(device devices.ControllableDevice, animations string) error {
+	if animations != "on" && animations != "off" {
+		return fmt.Errorf("invalid value for animations '%s', must be 'on' or 'off'", animations)
+	}
+
+	configurable, ok := device.(devices.AnimationConfigurable)
+	if !ok {
+		utils.Verbose("animations not supported on %s (%s), skipping", device.ID(), device.Platform())
+		return nil
+	}
+
+	err := configurable.SetAnimationsEnabled(animations == "on")
+	if err != nil {
+		return fmt.Errorf("failed to apply animations setting: %v", err)
+	}
+
+	return nil
+}

devices/android.go

@@ -1701,6 +1701,30 @@ func (d *AndroidDevice) SetOrientation(orientation string) error {
 	return nil
 }
 
+// SetAnimationsEnabled toggles the three global animation scales. Setting them
+// to 0 disables animations for stable screenshots; 1 restores the defaults.
+func (d *AndroidDevice) SetAnimationsEnabled(enabled bool) error {
+	scale := "0"
+	if enabled {
+		scale = "1"
+	}
+
+	scaleSettings := []string{
+		"window_animation_scale",
+		"transition_animation_scale",
+		"animator_duration_scale",
+	}
+
+	for _, setting := range scaleSettings {
+		_, err := d.runAdbCommand("shell", "settings", "put", "global", setting, scale)
+		if err != nil {
+			return fmt.Errorf("failed to set %s: %v", setting, err)
+		}
+	}
+
+	return nil
+}
+
 func (d *AndroidDevice) getCrashLog() (string, error) {
 	output, err := d.runAdbCommand("logcat", "-b", "crash", "-d", "-v", "year")
 	if err != nil {

devices/animations_test.go

@@ -0,0 +1,24 @@
+package devices
+
+import "testing"
+
+// The animations setting is fire-and-forget and platform-specific: Android
+// applies it via adb, while iOS/simulator are expected to no-op. Callers rely
+// on the AnimationConfigurable type assertion to decide which path to take, so
+// this test pins down which device types satisfy the capability.
+func TestAnimationConfigurableImplementers(t *testing.T) {
+	var android any = (*AndroidDevice)(nil)
+	if _, ok := android.(AnimationConfigurable); !ok {
+		t.Error("AndroidDevice should implement AnimationConfigurable")
+	}
+
+	var ios any = IOSDevice{}
+	if _, ok := ios.(AnimationConfigurable); ok {
+		t.Error("IOSDevice should not implement AnimationConfigurable (no-op expected)")
+	}
+
+	var simulator any = SimulatorDevice{}
+	if _, ok := simulator.(AnimationConfigurable); ok {
+		t.Error("SimulatorDevice should not implement AnimationConfigurable (no-op expected)")
+	}
+}

devices/common.go

@@ -155,6 +155,12 @@ type ControllableDevice interface {
 	GetAppContainerPath(bundleID string) (string, error)
 }
 
+// AnimationConfigurable is implemented by devices that can toggle system
+// animations. Devices that don't implement it are treated as a no-op by callers.
+type AnimationConfigurable interface {
+	SetAnimationsEnabled(enabled bool) error
+}
+
 // WebViewable is implemented by devices that support webview inspection and control.
 type WebViewable interface {
 	ListWebViews() ([]WebViewInfo, error)

server/dispatch.go

@@ -29,6 +29,7 @@ func GetMethodRegistry() map[string]HandlerFunc {
 		"device.boot":                     handleDeviceBoot,
 		"device.shutdown":                 handleDeviceShutdown,
 		"device.reboot":                   handleDeviceReboot,
+		"device.settings.apply":           handleSettingsApply,
 		"device.dump.ui":                  handleDumpUI,
 		"device.apps.launch":              handleAppsLaunch,
 		"device.apps.terminate":           handleAppsTerminate,

server/server.go

@@ -616,6 +616,11 @@ type IoOrientationSetParams struct {
 	Orientation string `json:"orientation"`
 }
 
+type DeviceSettingsApplyParams struct {
+	DeviceID   string  `json:"deviceId"`
+	Animations *string `json:"animations,omitempty"` // "on" or "off"
+}
+
 type DeviceBootParams struct {
 	DeviceID string `json:"deviceId"`
 }
@@ -815,6 +820,29 @@ func handleIoOrientationSet(params json.RawMessage) (any, error) {
 	return okResponse, nil
 }
 
+func handleSettingsApply(params json.RawMessage) (any, error) {
+	if len(params) == 0 {
+		return nil, fmt.Errorf("'params' is required with fields: deviceId")
+	}
+
+	var settingsParams DeviceSettingsApplyParams
+	if err := json.Unmarshal(params, &settingsParams); err != nil {
+		return nil, fmt.Errorf("invalid parameters: %w. Expected fields: deviceId, animations", err)
+	}
+
+	req := commands.ApplySettingsRequest{
+		DeviceID:   settingsParams.DeviceID,
+		Animations: settingsParams.Animations,
+	}
+
+	response := commands.ApplySettingsCommand(req)
+	if response.Status == "error" {
+		return nil, fmt.Errorf("%s", response.Error)
+	}
+
+	return okResponse, nil
+}
+
 func handleDeviceBoot(params json.RawMessage) (any, error) {
 	if len(params) == 0 {
 		return nil, fmt.Errorf("'params' is required with fields: deviceId")