Mirrors/PowerToys
1
0
Fork 0
mirror of https://github.com/microsoft/PowerToys.git synced 2026-08-29 10:09:43 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
bea1b8e2476c665693af6ec0fc6d2c281b3627de
PowerToys/doc/devdocs/modules/powerrename.md
Gleb Khmyznikov bea1b8e247 [UITests][PowerRename] Migrate to new .Next and add more UI tests (#50096) 
## Summary of the Pull Request

Adds a `PowerRename.UITests.Next` suite powered by winappcli and
automates all 18 scenarios from #40663. The suite covers PowerRename
settings, search and replace behavior, regular expressions, formatting
and filtering options, file-list interactions, and both classic and
Windows 11 context-menu workflows.

The PR also stabilizes shared `UITestAutomation.Next` runner lifetimes
and settings restoration, adds automation IDs for the original and
renamed counters, and prepares unsigned CI builds for PowerRename shell
testing. CI now signs the sparse context-menu MSIX and the
runner/Settings IPC companions with a disposable machine-trusted test
identity.

## PR Checklist

- [x] Closes: #40663
- [x] **Communication:** I've discussed this with core contributors
already. If the work hasn't been agreed, this work might be rejected
- [x] **Tests:** Added/updated and all pass
- [x] **Localization:** All end-user-facing strings can be localized
- [x] **Dev docs:** Added/updated
- [x] **New binaries:** Not applicable; no new shipped product binaries
are added
   - [x] JSON for signing: Not applicable
   - [x] WXS for installer: Not applicable
- [x] YML for CI pipeline: The new UI-test project is discovered through
the existing `*UITest*.csproj` pipeline flow and is registered in
`PowerToys.slnx`
   - [x] YML for signed pipeline: Not applicable
- [x] **Documentation updated:** Not applicable; there are no
user-facing behavior or documentation changes

## Detailed Description of the Pull Request / Additional comments

### PowerRename UI tests

- Adds a 25-case `PowerRename.UITests.Next` executable covering all 18
checklist items from #40663.
- Exercises classic context-menu registration on Windows 10 and Windows
11.
- Exercises the signed Windows 11 tier-1 context menu, including icon
visibility and real invocation with an Explorer selection.
- Covers search/replace preview and application, text formatting,
file/folder/subfolder inclusion, filename/extension scope, enumeration,
case sensitivity, match-all behavior, regular expressions, file
timestamps, Boost syntax, MRU autocomplete, persisted values, and
file-list selection/filtering.
- Preserves the existing legacy tests.

### Test reliability and automation hooks

- Reuses one runner/Settings lifetime across the complete PowerRename
suite to avoid repeated cold launches on constrained agents.
- Retains and restores global settings for the full class lifetime and
verifies that both Settings and the runner remain healthy.
- Propagates scope and PowerRename cleanup failures instead of silently
leaking process or profile state.
- Adds `OriginalCount` and `RenamedCount` automation IDs. These are
automation-only metadata and do not change the visible UI.
- Uses stable preview samples, exact count targeting, authoritative
Explorer selection, readable classic-menu inventories, and live UIA
visibility for popup items.

### Unsigned CI build support

- Extends the existing sparse-package test signer with required
Authenticode companion files.
- PowerRename jobs sign `PowerToys.exe` and `PowerToys.Settings.exe`
with the same disposable machine-trusted test identity used for sparse
MSIX packages.
- This preserves Release IPC authentication while allowing Settings
module-toggle commands to work on unsigned PR builds.
- Windows 11 and ARM64 PowerRename jobs require a validly signed
`PowerRenameContextMenuPackage.msix` before tests start.

## Validation Steps Performed

### Builds and discovery

- `PowerRename.UITests.Next` Debug x64 build: passed
- `PowerRename.UITests.Next` Debug ARM64 cross-build: passed
- `PowerRenameUI` Release x64 build: passed
- `UITestAutomation.Next.UnitTests` Debug x64 build: passed
- `UITestAutomation.Next.UnitTests`: 16/16 passed
- Microsoft.Testing.Platform discovery: 25 unique PowerRename test cases

### Local VM matrix

All runs used the complete unfiltered `TestCategory=PowerRename` suite
and restored the standard user's settings file byte-for-byte.

| Guest | Profile | Result |
|---|---|---:|
| Windows 10 x64 | Default, 4 vCPU / 8 GB | 25/25 | 
| Windows 10 x64 | Constrained, 1 vCPU / 4 GB | 25/25 | 
| Windows 11 x64 | Default, 4 vCPU / 8 GB | 25/25 | 
| Windows 11 x64 | Constrained, 1 vCPU / 4 GB | 25/25 | 

### Azure DevOps UI Test Automation

- Final build: [155646235 /
20260824.1](https://dev.azure.com/microsoft/Dart/_build/results?buildId=155646235)
- Source revision: `4496683104aea622b30179909bd6e95a17d5500f`
- ARM64: 25/25 passed
- Windows 10 x64: 25/25 passed
- Windows 11 x64: 25/25 passed
- Total: 75/75 passed, with zero failed, skipped, not-executed, or
unanalyzed results
- ARM64 and x64 Release product builds succeeded and published their
normal artifacts
- Signing steps verified the PowerRename sparse MSIX where applicable
and both IPC companion executables on every PowerRename test job

<img width="372" height="314" alt="image"
src="https://github.com/user-attachments/assets/bc303673-0325-4f85-8d70-ef93110baf5b"
/>
2026-08-26 00:26:10 +02:00

5.7 KiB
Raw Blame History

PowerRename

Public overview - Microsoft Learn

Quick Links

All Issues
Bugs
Pull Requests

PowerRename is a Windows shell extension that enables batch renaming of files using search and replace or regular expressions.

Overview

PowerRename provides a powerful and flexible way to rename files in File Explorer. It is accessible through the Windows context menu and allows users to:

  • Preview changes before applying them
  • Use search and replace with regular expressions
  • Filter items by type (files or folders)
  • Apply case-sensitive or case-insensitive matching
  • Save and reuse recent search/replace patterns

Architecture

PowerRename consists of multiple components:

  • Shell Extension DLL (context menu integration)
  • WinUI 3 UI application
  • Core renaming library

Technology Stack

  • C++/WinRT
  • WinUI 3
  • COM for shell integration

Context Menu Integration

PowerRename integrates with the Windows context menu following the PowerToys Context Menu Handlers pattern. It uses a dual registration approach to ensure compatibility with both Windows 10 and Windows 11.

Registration Process

The context menu registration entry point is in PowerRenameExt/dllmain.cpp::enable, which registers:

  • A traditional shell extension for Windows 10
  • A sparse MSIX package for Windows 11 context menus

For more details on the implementation approach, see the Dual Registration section in the context menu documentation.

Code Components

dllmain.cpp

Contains the DLL entry point and module activation/deactivation code. The key function RunPowerRename is called when the context menu option is invoked, which launches the PowerRenameUI.

PowerRenameExt.cpp

Implements the shell extension COM interfaces required for context menu integration, including:

  • IShellExtInit for initialization
  • IContextMenu for traditional context menu support
  • IExplorerCommand for Windows 11 context menu support

Helpers.cpp

Utility functions used throughout the PowerRename module, including file system operations and string manipulation.

PowerRenameItem.cpp

Represents a single item (file or folder) to be renamed. Tracks original and new names and maintains state.

PowerRenameManager.cpp

Manages the collection of items to be renamed and coordinates the rename operation.

PowerRenameRegEx.cpp

Implements the regular expression search and replace functionality used for renaming.

Settings.cpp

Manages user preferences and settings for the PowerRename module.

trace.cpp

Implements telemetry and logging functionality.

UI Implementation

PowerRename uses WinUI 3 for its user interface. The UI allows users to:

  • Enter search and replace patterns
  • Preview rename results in real-time
  • Access previous search/replace patterns via MRU (Most Recently Used) lists
  • Configure various options

Key UI Components

  • Search/Replace input fields with x:Bind to SearchMRU/ReplaceMRU collections
  • Preview list showing original and new filenames
  • Settings panel for configuring rename options
  • Event handling for SearchReplaceChanged to update the preview in real-time

UI tests

The migrated PowerRename.UITests.Next project drives the module through Microsoft.PowerToys.UITest.Next and winappcli. Keep these module-specific constraints in mind:

  • The PowerRename UI receives its selected files on the command line. Tests launch PowerToys.PowerRename.exe directly with an argument per path, while retaining the runner/Settings scope for module enablement and shell registration.
  • Windows 11 tier-1 context-menu tests require a signed and trusted PowerRenameContextMenuPackage.msix. Unsigned builds can still exercise the classic menu.
  • UseBoostLib is read when the regex engine is constructed, so changing it requires a fresh PowerRename process.
  • Shell handlers read global/module settings independently. Tests wait for persisted settings and restart Explorer after registration changes instead of treating the Settings control state as the final signal.

See the UI tests framework for build, local-VM, and pipeline workflows.

Debugging

Debugging the Context Menu

See the Debugging Context Menu Handlers section for general guidance on debugging PowerToys context menu extensions.

Debugging the UI

To debug the PowerRename UI:

  1. Add file paths manually in \src\modules\powerrename\PowerRenameUILib\PowerRenameXAML\App.xaml.cpp
  2. Set the PowerRenameUI project as the startup project
  3. Run in debug mode to test with the manually specified files

Common Issues

  • Context menu not appearing: Ensure the extension is properly registered and Explorer has been restarted
  • UI not launching: Check Event Viewer for errors related to WinUI 3 application activation
  • Rename operations failing: Verify file permissions and check for locked files
Reference in New Issue View Git Blame Copy Permalink