Skip to content

Known Limitations

The complete conversion coverage matrix — what converts automatically, what is approximated with warnings, and what fails closed — lives in supported_versions.md. This page covers the boundaries and caveats that apply to the current release.

Phoenix offers exactly two conversion paths: local filesystem conversion of UFT test directories on disk, and whole ALM project conversion. Both are AOM-canonical — each test is opened, converted, and re-saved through UFT's own Automation Object Model, producing a structurally valid, runnable Python test for UFT 26.1 or 26.3 (never hand-patched binary Test.tsp/.usr, never a source-only transpile). Both therefore require UFT installed locally; the filesystem path saves to a local directory, the ALM path saves back into ALM (preserving each test's ID). ALM conversion is all-or-nothing for a given domain/project — you cannot convert an arbitrary subset. This is a hard rule, not a limitation to work around: a callee action runs inside the caller's script engine, so a call chain must be uniformly one engine (all Python). Converting the whole project keeps every chain uniform and lets Phoenix rebuild cross-test shareable-action references natively (see below). The CLI-only --allow-partial-conversion override exists, but it knowingly leaves the project half Python and half VBScript and is not a safe way to convert a subset; see alm_safety.md.

Conversion boundaries (fail-closed)

These constructs are refused rather than converted. ALM project conversion always runs at strict, so each one blocks its test and stops the whole-project run unless it is overridden with the CLI-only --allow-blockers (the GUI has no override). Local filesystem conversion follows its Strictness setting, which changes what "refused" means — see Strictness on the local path below.

  • Dynamic code — Execute / Eval used as a statement (ExecuteGlobal is refused the same way). No deterministic translation exists; replace it in the source with explicit dispatch (a custom mapping rule cannot clear this blocker). (Eval inside an expression is a different case: the filesystem scan raises it, but neither path refuses it — see below.)
  • ExecuteFile — every ExecuteFile statement is refused, whether or not the library it loads is linked to the test. Link the .qfl to the test (as an ALM Test Resource for ALM conversion, or on the test's library list for local conversion) so it is converted once to a Python Function Library (.pfl) and linked automatically, then delete the ExecuteFile line — linking the library does not clear the blocker.
  • Parameter() names with nothing to resolve against. Action-level and test-level parameter definitions are both harvested from the source test and re-authored on the converted one, and a main-flow Parameter() read resolves against the test-level set. What fails closed is a name that is in neither: in an action with no action-level definitions of its own — the main flow always — a Parameter() name absent from the test-level definitions blocks the test. Only default values are carried; test-set run-time overrides do not propagate. The check is per action and needs UFT, so it runs during a conversion or a Deep ALM analysis, never in a standard ALM analysis. On a local filesystem conversion this blocker is waived at the default standard strictness, and unlike the constructs above it leaves no trace in the script: the Parameter() call is published unchanged, with no # SKIPPED comment, and the test fails at run time with UFT's Parameter <name> not found. Use strict if you want the conversion to refuse it.
  • Cross-test reusable-action callers require whole-project conversion. A test that calls another test's reusable actions (RunAction "X [OtherTest]") executes the callee inside the caller's engine, so the whole chain must be uniformly Python — a mixed VBScript/Python chain fails at runtime (a VBScript caller executing a Python callee errors on line 1). This is why ALM conversion is whole-project: converting the entire project together keeps every chain uniform and lets Phoenix see inbound references from any test. When a caller is converted, its external "call to existing action" references are reconstructed natively (via UFT's AddExistingAction) so the shareable action stays in its own test and is consumed by reference — the action body is never copied or inlined into the caller.

Strictness on the local path. strict refuses the test: the construct becomes a # BLOCKED comment and nothing is built. standard — the shipped default — still builds and publishes the test, with the construct replaced by a # SKIPPED unsupported … comment and the blocker recorded as waived (OVERRIDE: proceeding despite N blocker(s) in the conversion notes). permissive publishes a raise NotImplementedError(...) stub in its place and records only a warning. At standard the construct is silently skipped rather than failed; at permissive it stops the action the moment it is reached. In both cases the verdict alone will not tell you, so read the conversion notes as well.

Checkpoint/OutputValue objects and GetROProperty-family APIs are flagged by the local filesystem scan only. There they are scan-report errors: they turn the run's verdict to no-go and are listed per line. ALM project analysis does not run those detectors at either depth, so an ALM project full of checkpoints can still report go. On both paths the line itself is still converted (the UFT Python API's property model differs), so review every such line before you approve the run. Before an ALM conversion, find them in your own source:

Get-ChildItem -Recurse -Include Script.mts,*.qfl,*.vbs |
  Select-String -Pattern '\.(Check|Output)\s*\(?\s*CheckPoint\s*\(|GetROProperty|GetTOProperty|SetTOProperty'

For an ALM project, run it over an export or over the downloaded folders named in the next section.

Not detected before conversion — find these yourself (known gap)

The local filesystem scan does not classify the first three constructs below. They raise no blocker and no finding that names them — at most a generic "Call statement or implicit-call syntax detected" warning, because the line parses as an ordinary procedure call — and warnings do not affect the go/no-go verdict. A filesystem scan of tests whose only issue is a GoTo still reports go_no_go: "go"; the conversion then refuses to build that test with "converted output is not valid Python".

ALM project analysis is the exception. It parses every converted action body, so those three are refused at analysis time by that same "converted output is not valid Python" blocker, which names the converted action and — where it can map it — the source line number, and cannot be overridden. That message describes itself as a converter defect — for the constructs below it is not one, and the fix is in the VBScript.

Search your tests for all four and remediate the VBScript before you convert:

  • GoTo <label> (and its inline form If … Then GoTo <label>) — the label and the jump are emitted verbatim; the action does not compile.
  • On Error GoTo <label> — emitted verbatim; the action does not compile. (On Error Resume Next and On Error GoTo 0 are supported.)
  • VBScript classes — Class … End Class, Property Get/Let/Set — emitted as calls (Class(Cart), Public(Property Get T)); the action does not compile.
  • Eval inside an expression (x = Eval("…"), as opposed to the statement form Eval "…") — emitted as a call to an undefined Eval, which does compile and then raises NameError at run time. The local filesystem scan does raise this one, as a dynamic-code error that turns the verdict to no-go; ALM analysis is silent on it, precisely because the Python it produces parses. It is the one case in the list that reaches a live run.

A pre-migration sweep of the source, run from the root of your test folders, finds them:

Get-ChildItem -Recurse -Include Script.mts,*.qfl,*.vbs |
  Select-String -Pattern '(?<![\w.])(GoTo\s+(?!0\b)\w+\s*(''.*)?$|Class\s+\w+\s*(''.*)?$|Property\s+(Get|Let|Set)\s+\w+|Eval\s*\()'

It deliberately keeps On Error GoTo 0 and member access such as obj.Class out of the results; treat every remaining hit as a review item (a match inside a comment or a string literal is a false positive), and note that a GoTo or Class statement followed on the same line by a : separator will not match.

For an ALM project, run the same sweep over an export, or over the folders a GUI Analysis or convert --alm --dry-run downloads under out\<run id>\alm_aom_work\ in the folder you launched Phoenix from: test_<id>_source holds each test's scripts and test_<id>_libraries its linked function libraries. Remediation is ordinary VBScript refactoring: replace GoTo with structured flow, replace a class with a function library, and replace Eval with explicit dispatch.

The filesystem scan does not classify GoTo, On Error GoTo <label> or VBScript classes, so that path's verdict does not reflect them the way the ALM path's does; this manual sweep is the control.

Semantic approximations (converted, with per-file warnings)

  • Empty, Null, and Nothing all convert to Python None; code that distinguishes them (IsEmpty vs IsNull vs TypeName) is approximate.
  • Eqv / Imp convert with boolean semantics: exact when the operands are conditions (If a = 1 Eqv b = 2), approximate on integers, where VBScript is bitwise (5 Eqv 3 is -7) — those sites are flagged per file and need review. Xor is not approximate: it converts exactly, integers included (5 Xor 3 is 6 in both languages).
  • Out-parameters do not propagate. VBScript passes ByRef by default, so a procedure that assigns one of its own parameters updates the caller's variable; Python parameters are always by value, so the caller keeps its old value. This applies whether or not ByRef was spelled — the keyword is almost never written in practice. Every procedure that WRITES a parameter is flagged per site — by the local filesystem scan, and by the converter's own per-file warnings on both paths — naming the parameters involved. Rewrite those helpers to return their value(s). Two cases are correctly not flagged because nothing is lost: an explicit ByVal parameter (VBScript does not propagate it either) and an element write into an array parameter (arr(0) = x, which propagates in both languages). That concerns the out-parameter warning only. The local filesystem analysis separately raises an error-severity finding on any literal ByRef or ByVal keyword, which turns the verdict to no-go; see supported_versions.md.
  • MsgBox / InputBox convert to non-blocking shims (print / default-return) so batch runs never hang on a dialog; tests designed around human acknowledgement change behavior by design.

Fixed in 1.3.4: text in an object description could change during conversion

Versions 1.3.3 and earlier converted some steps wrongly and reported them as clean. Both conversion paths were affected. The converted step was valid Python, raised no blocker and no warning, and left the go/no-go verdict untouched, so nothing in the reports pointed at it. This release converts these steps correctly.

Which steps. A step that calls a method without parentheses around its arguments, where the object part of the step (everything before the method name) holds a quoted string containing a backslash or a doubled quote (""), or joins values with & outside the quotes:

Browser("Main").Page("Main").WebEdit("name:=\bUser\b").Set "admin"
Window("regexpwndtitle:=C:\\Reports\\.*").Activate 1
Browser("Main").Page("Main").WebEdit("name:=Say ""hi""").Set "x"
Browser("Main").Page("Main").WebEdit("name:=" & strField).Set "x"

The arguments ("admin", "x") were converted correctly. The object part was copied into the Python as written, and Python reads quoted text by its own rules:

  • A backslash started an escape. \b, \n, \t, \r, \f, \v, \a, and \0 to \7 (an octal character code, so a folder name such as \2024 changed too) turned into control characters. A doubled backslash (\\), the usual way to match a real backslash in a regular expression or to write a \\server share, became a single one. \x, \u, \U and \N followed by a valid code (\x41) became the character that code names. Each of these changed the description without any error. \d, \s, \w and \. happened to come through unchanged. \x, \u, \U or \N without a valid code produced Python that does not compile, and those tests were refused rather than converted.
  • A doubled quote was dropped: Say ""hi"" became Say hi.
  • & became a different operator. Where either side was text, the step failed with an error when it ran. Where both sides were whole numbers (oItems(i & j)), the step silently used a different value.

An & inside a quoted string ("text:=Terms & Conditions") was not affected.

The same happened to the object part of a property assignment that holds no := (Browser("Main").WebEdit("Path\new").Object.value = "x", with or without Set in front; with := the step was refused, see below), and to such a step inside a With block (.WebEdit("name:=\bUser\b").Set "x"), on an OptionalStep line, after Then or Else on a one-line If, or after a : separator. These were always converted correctly: calls with parentheses (.Set("admin")), steps with no arguments (.Click), and the object in Set x = …, x = …, If, Do, Loop and While conditions, Select Case, For Each and With lines.

What it did at run time. The step looked for an object description you did not write. Usually that fails the step with an object-not-found error. Under On Error Resume Next, or where the changed regular expression still matches an object, the step can instead be skipped, or act on another object, without failing the test.

Three related shapes failed loudly in earlier versions, rather than converting wrongly without notice, and now convert:

  • an object part that indexes a VBScript array (arrEdits(0).Set "x") was written as a call and failed at run time with a TypeError;
  • a property assignment whose object part contains := (Browser("title:=Home").WebEdit("name:=q").Object.value = "x") was refused with "converted output is not valid Python";
  • an OptionalStep line with a doubled quote in its arguments was refused because the step "would be LOST at run time".

Find the tests an earlier version converted. Search the VBScript the conversion started from. On the ALM path that is the run folder's first-sight copies, out\<run id>\alm_aom_work\alm_rollback\test_<id>_source, and the .qfl libraries in alm_aom_work\test_<id>_libraries. On the filesystem path it is the source tree after Convert Mode new (which leaves it untouched); after an in-place conversion it is the <name>.bak folder Phoenix set aside beside each converted test, or version control. Run this from the folder that holds them:

Get-ChildItem -Recurse -Include Script.mts,*.qfl,*.vbs |
  Select-String -Pattern '(^|:|\bThen\s|\bElse\s)\s*((Call|Set)\s+)?\.?\w[\w.]*\(.*(\\|""|&).*\)(\.\w+)+(\s+[^\s=]|\s*=)'

Every affected step written on one line matches. Review each hit: an empty string ("") or an & inside quotes in the object part, or a backslash or & in the arguments of a line that has further parentheses, also matches and is harmless. The array shape above does not match; it failed loudly when the test ran.

If you no longer have the VBScript, search the converted scripts instead (the Script.pts of each action, and the converted .pfl libraries). Phoenix writes a backslash as \\, a quote inside a string as \", and joins text with VBConcat(…), so a damaged single backslash, doubled quote or & stands out:

Get-ChildItem -Recurse -Include Script.pts,*.pfl |
  Select-String -Pattern '^\s*[^#\s]' |
  Where-Object {
    $line = $_.Line -replace '"(\\[rnt])+"', '""' -replace 'pair\[0\] & pair\[1\]', ''
    $line -match '(?<!\\)\\[^\\"u]|"""|\w""|""\w|"\s*&|&\s*"' -or
      ($line -replace '"(\\.|[^"\\])*"', '""') -match '[\w)\]]\s+&\s+[\w(]'
  }

This search cannot find every affected step. A damaged doubled backslash (\\ in the VBScript, which Python read as one) and a damaged \u code look exactly like a correct conversion. A doubled quote in the middle of the text with a space or punctuation on both sides ("text:=Click "" here"), an & written without spaces between two names (a&b) and the array shape above are not matched either. If your object descriptions use \\ (a regular expression that matches a real backslash, such as C:\\Reports\\.*, or a \\server share), a doubled quote or & that way, find those tests from the VBScript or the rollback copies, or review every converted object description that holds \\ or a "" that is not an empty string.

For an ALM project, a GUI Analysis or convert --alm --dry-run of the converted project downloads each test's current scripts into out\<run id>\alm_aom_work\test_<id>_source; run the search there. Run that analysis under a new Analysis Run ID (on the command line, a new --run-id), or first do the search in § Shared object repositories on caller tests (fixed in 1.3.4) below: an analysis in the run folder you converted in rewrites that folder's alm_aom_results.json and can delete its migration_log.txt, the record that search reads. An action that was already Python before you converted can match too: review it as your own code.

What to do. For each affected test, convert it again from its pre-conversion copy with this release, or correct the object part by hand in the converted script.

  • ALM path. Restore the test (uft-migrate restore, alm_safety.md § Rolling back), then run the conversion under a new run id: an earlier run id skips every test that run already converted (playbook.md § 3. Rule hardening describes the same sequence).
  • Filesystem path, Convert Mode new. Convert again into a new Output Root, or into the same one with Overwrite Policy backup or overwrite. The default, fail, refuses every test whose output already exists.
  • Filesystem path, Convert Mode in-place. Move the converted <name> aside and rename <name>.bak back to <name> (or restore the test from version control) before converting again. Converting the already-converted <name> keeps its Python as it stands, so the damage stays.
  • By hand. Write the description as the VBScript meant it: double each backslash ("name:=\\bUser\\b", "regexpwndtitle:=C:\\\\Reports\\\\.*") and write a quote inside the string as \" ("name:=Say \"hi\""). For a damaged &, prefer converting again. If you edit it, use VBConcat (WebEdit(VBConcat("name:=", strField))) only in a script that already calls VBConcat elsewhere: Phoenix installs that helper only where the conversion needed it, and anywhere else the step stops with a NameError. Otherwise write "name:=" + str(strField), which gives None instead of an empty string when the variable is Empty.

Test-level artifacts not carried

A converted test is rebuilt through the AOM, not copied. Only what Phoenix explicitly re-applies survives; everything else in the source test comes out at UFT's defaults. That is the rule to plan against, and it is the safer way round from a list of known gaps, because the gaps below are the cases we have measured and can advise on — they are examples, not an exhaustive inventory.

What is re-applied in both conversion paths:

  • the action map and action names, and cross-test shareable-action references (rebuilt natively via AddExistingAction)
  • per-action object repositories (copied, and content-hash verified)
  • the root Default.xls / .xlsx DataTable workbook
  • action-level and test-level parameter definitions
  • the linked function libraries

What only ALM project conversion re-applies:

  • the per-action shared-repository (.tsr) associations — a test whose associations UFT cannot read, and which uses one, fails rather than converting without it; 1.3.3 and earlier could drop them on a test that calls another test's actions and, without a note, on any test whose repositories UFT could not read (fixed in 1.3.4, see below)
  • six Settings.Run fields: iteration mode, start and end iteration, on-error behavior, object sync timeout, disable smart identification
  • the associated add-in set

A local filesystem conversion carries none of those three, and the consequences are concrete: a single-iteration source test comes out running every DataTable row; a shared object repository is not associated at all, with no warning; and the built test is saved with whatever add-ins the UFT session happens to have loaded, which changes which class claims a window (see the add-in note below). Set these on the converted test in UFT, or convert through ALM.

The counts in brackets below are how often each gap was hit in the reference validation (116 tests, 239 actions). They are evidence that the gap is real, not a statement of how often it will affect you.

  • UFT Environment variables are not carried. Neither internal user-defined variables nor the association to an external environment XML file. Nothing in the rebuild reads or writes them, so a converted test starts with an empty Environment and every Environment("name") read returns nothing. Local filesystem analysis flags Environment(...), Environment.Value and Environment.LoadFromFile usage; ALM project analysis does not. Search for them before you convert — for scripts on disk, for example Get-ChildItem -Recurse -Include Script.mts,*.qfl,*.vbs | Select-String -Pattern 'Environment\s*(\(|\.Value|\.LoadFromFile)'; for ALM tests, search the test and library scripts in UFT or ALM — then re-create the variables on the converted test or move them into the DataTable.
  • An externally linked Data Table is not carried. Only a Default.xls / .xlsx sitting at the test root is copied. A test pointed at a Data Table elsewhere (Settings → Resources → Data Table) comes out on the rebuilt test's own workbook, silently losing its data source.
  • Run-logic and configuration profiles (default.usp, default.cfg) are not carried. They are generated by the AOM for the rebuilt flow. The run order survives because Action0's script is re-emitted with its RunAction calls, and on the ALM path the six Settings.Run fields above are re-applied — but anything else those profiles held (additional Vuser profiles, per-action run-logic customization) is not. Every test in the reference test set shared one identical default.usp, so that validation could not have detected this and did not.
  • Action descriptions are not carried. Each rebuilt action is authored with an empty description.
  • Recovery scenarios are not carried. [6 of 116] UFT 26.1 does not support recovery scenarios for Python tests at all, so there is nothing to carry them into. UFT 26.3 supports them, but only as Python recovery scenarios (.prs), a different file format from the VBScript .qrs the source references, and Phoenix does not convert .qrs to .prs. On 26.1 the gap cannot be closed; on 26.3, re-author the scenarios as .prs and associate them with the converted tests by hand (not tested by Phoenix). Any test relying on a recovery scenario to survive an unexpected dialog, crash or session state will behave differently after conversion: the recovery never fires. Identify these before you convert — neither analysis path is a reliable detector. ALM project analysis records a test's linked recovery scenarios only as a per-asset note (Linked ALM Test Resources: … Recovery scenario) in alm_analysis_results.json; it raises no finding, does not show in the HTML reports and does not affect the verdict. The local filesystem scan counts the .qrs files it finds under the source roots, but warns only when a single script line both names a .qrs file and contains the word recovery, and a scenario associated in Test Settings is never named in script text. Check File → Settings → Recovery in UFT, or the test's Test Resources in ALM, and either re-author the scenarios in 26.3 or handle the condition in the script.
  • Analog recording tracks (AnalogTrackList.dat) are not carried. [2 of 116, both inert] Analog replay records literal mouse paths and keystroke timing; it has no Python equivalent. A test that genuinely calls RunAnalog still converts, with no blocker and no finding that names it, but the analog track it replays is not carried, so those steps cannot replay. Re-author them as ordinary object steps. In the reference test set both affected tests carried the file without ever invoking analog replay, so nothing was lost there — do not read that as the general case. Search your tests for RunAnalog before converting.
  • Debug watch expressions (Watches.xml) are not carried. [12 of 116] IDE-only debugging aids saved with the test; they have no effect on execution. Re-add them in UFT if you want them. No action required.
  • Record-and-Run / launcher settings are not round-tripped. [all tests] The test's Record and Run Settings — which browser or application UFT launches — are left at the converted test's defaults rather than copied. This is deliberate: the AOM exposes a writable Browser on the Web launcher but no consistent Active flag across launcher types, so copying the source's values can make UFT launch the wrong application. A test that depends on Record and Run Settings to start its AUT will not start it after conversion. Set Record and Run Settings on the converted test, or drive launch from the script with SystemUtil.Run — which is what the reference test set does throughout.

Shared object repositories on caller tests (fixed in 1.3.4)

Fixed in 1.3.4. Versions 1.3.3 and earlier could drop the shared object repository (.tsr) of a test that both calls another test's reusable actions and associates a shared repository itself. This concerns ALM project conversion, the only path that re-applies shared repositories at all; a local filesystem conversion drops every one of them, as the list above says. The converted test uploaded and verified clean, then failed at run time with Cannot find the "<object>" object's parent, because no object that resolves through the repository could be found. Those versions reported the loss only as a note on the test: [warning] shared object repository NOT carried into the rebuilt test: <repository>. A test that calls no other test, or associates no shared repository, was not affected.

The cause: once the rebuild adds a call to another test's action, UFT's automation interface no longer reports the test's own actions reliably, and the step that associates the repositories looked each action up there and found none. Phoenix now associates each repository on the action as it builds it. It then checks the saved test against what UFT reports for each of the source test's actions. A test that would still come out without one of those is refused rather than uploaded: it ends aom-build-failed with shared object repository NOT carried into the rebuilt test: . The source associates it, … refusing to upload the test without it, and like any failed test it stops the conversion before anything of that test is uploaded.

A repository named only in the test's files is reported as a warning on that test, not refused: [warning] the source test's files associate shared object repository , which UFT reports for none of its actions …. ALM keeps the files of an action that was deleted from a test or replaced, and they still name the repository that action used, so a name only the files carry may belong to no action of the test. If one of the test's actions does use it, associate it again in UFT. Only an action's repository associations count: a repository an action's description mentions is not one.

A related case is refused too. To carry a test's shared repositories, the conversion first asks UFT which ones each action uses. When UFT fails that read with one of its known transient faults (a license or COM hiccup), Phoenix tries it up to twice more, noting each retry as object-repository harvest hit a transient UFT/COM fault (attempt n/3), retrying: …. If the read still fails, Phoenix reads the downloaded source test's action files itself. A test that names a .tsr there, or whose files cannot be read, fails with aom-build-failed (the source test shared object repositories could not be harvested (…); refusing to rebuild without them because the source associates …). Earlier versions converted it without its repository, and it failed only at run time. A test that names none converts as before, with a note that its shared repositories could not be harvested. An action whose repositories UFT cannot read now fails that read in the same way; earlier versions left that action out of UFT's answer without a word.

If you converted with 1.3.3 or earlier, check every test that both calls another test's actions and uses a shared object repository. Search the run folder for shared object repository not carried, ignoring case: each test it names most likely lost its repository. Before you re-associate one, open it in UFT (Resources → Associate Repositories) to confirm the repository is missing: those versions also named a test that associates its repository by file name alone, even when it kept it. Search migration_log.txt (for example Select-String -Path migration_log.txt -Pattern 'shared object repository not carried'): it is the complete record. alm_aom_results.json holds only the last launch's results, and a test that launch carried forward from an earlier one (after a crash, a planned restart of the conversion process, or a re-run with the same run id) keeps only an Already converted note there, not this one. If migration_log.txt is already gone, the note cannot be relied on: confirm each test that uses a shared object repository as for the silent case below.

Search before you run anything else in that run folder, or copy the folder somewhere safe first. Every analysis in the folder rewrites alm_aom_results.json, and a Migration Console analysis with Overwrite previous analysis outputs ticked (the default) deletes migration_log.txt unless the last run in the folder was a run conversion (the Migration Console's, or uft-migrate run); the first analysis after that conversion counts as that last run, so the second deletes it. To analyze the converted project without touching that record, for example for the search in § Fixed in 1.3.4: text in an object description could change during conversion above, enter a new Analysis Run ID first (on the command line, a new --run-id).

The shared object repository not carried note does not cover the silent case above: an action whose repositories UFT could not read left no note at all, on any test that uses a shared object repository, caller or not. Such a test can be confirmed only by running it, or by comparing its converted actions' Resource.mtr files with the pre-conversion copy in the run folder's alm_aom_work\alm_rollback\test_<id>_source\. Compare the associations UFT shows (Resources → Associate Repositories), not text found in the files: a Resource.mtr file can keep an old copy of its content, so a text search can find a repository the action no longer associates. Do not check in ALM — it will lie to you. The ALM asset relation between the test and the .tsr resource survives even when the action-level association is lost, so the repository still shows as a linked resource on the test while no action uses it. UFT resolves objects through the association stored in each action (Action<N>/Resource.mtr), not through the ALM relation.

To repair an affected test, re-associate the repository on it in UFT (Resources → Associate Repositories), or restore the test from its pre-conversion copy and convert it again with this version. Converting the already-converted test again does not repair it: the conversion carries what the test it reads associates, and the converted test no longer associates the repository. That conversion names the lost repository in a [warning] note on the test, because ALM keeps the files of the action it replaced, but it does not associate it again.

Two further differences are expected and benign rather than limitations, but are called out because a byte-level comparison of source against build will surface them: each converted action receives a new GUID, author and timestamp (it is a newly authored asset), and action folder numbers may shift (a source Action1 can land as Action2, because UFT's action-folder allocator never reuses a number). Action names — which are what scripts and cross-test references resolve by — are preserved exactly, as are the object repositories and the DataTable. The run configuration and the shared-repository associations are preserved on the ALM path only; on the filesystem path expect them to differ, per the re-apply list above.

A third difference applies to the ALM path, looks alarming, and is not: the converted test's .usr file lists fewer add-ins than the source's. That section records which add-ins were installed when the test was saved, not which the test is associated with, and it is typically identical across an entire project. Phoenix carries the associated set reported by GetAssociatedAddinsForTest, which is the minimal set the test actually needs — a test driving Browser/Page objects gets Web; one driving WpfWindow gets WPF and UI Automation. This is deliberate and load-bearing: an over-broad add-in set changes which class claims a window, and has been measured to break object identification outright (WpfWindow stops matching and every object beneath it fails). Compare add-ins with GetAssociatedAddinsForTest, not with the .usr. A local filesystem conversion carries no add-in set at all, so the built test keeps whichever add-ins the UFT session had loaded — check and set them by hand.

What the reference validation did and did not exercise

A clean conversion only proves the paths the source tests actually walked. The reference test set (116 VBScript tests, 239 actions) did not exercise the features below, or exercised only the narrow slice each row names, so while Phoenix has unit coverage and, in several cases, explicit handling for them, they have not been proven end-to-end on a real conversion. Treat any of these in your own tests as needing a pilot conversion and a run comparison before a production wave — convert a representative handful first rather than the whole project blind:

Not exercised Why it matters
Environment variables (Environment(...)) and external environment XML files Not merely untested — not carried at all; see the entry above. No test in the reference test set used them, so the gap was never exercised end-to-end either.
Active Screen data Not carried and never exercised; Active-Screen-dependent maintenance workflows do not survive.
Virtual objects No conversion path has been demonstrated.
LoadFunctionLibrary and ExecuteFile at run time The linked-library path is well covered (39 tests); loading a library dynamically from script is not. Every ExecuteFile statement is refused on the ALM path; on the filesystem path its treatment follows the Strictness setting (see Strictness on the local path).
Runtime Recovery.* API calls Distinct from recovery scenarios above; the runtime object is untested.
WMI beyond Win32_Process (winmgmts:) Only Win32_Process ran end to end — enumeration (InstancesOf), a filtered ExecQuery, property reads, collection .count and Terminate(), in the reference test set's process-closing helper (see the process-scan note below). Other namespaces and classes have unit coverage only.

Checkpoints are the exception to read carefully. They were exercised: the reference test set's converted tests ran them, and its approved regression set reported the same checkpoint count as its VBScript baseline. What is missing is detection — ALM project analysis does not flag a checkpoint, an OutputValue or a GetROProperty-family call at all, so find them yourself with the sweep above and review every such line before you approve the run.

The constructs Phoenix is known not to detect before a filesystem conversion — GoTo, On Error GoTo <label>, VBScript Class and Property Get/Let/Set — also did not appear in the reference test set, and nor did Eval inside an expression, which the filesystem scan does raise. The pre-migration sweep above is the control for all four; run it.

Function libraries (.qfl → .pfl, shared and linked)

A VBScript function library (.qfl) linked to a test is converted once to a Python Function Library (.pfl, the Python analog of .qfl) and linked to each converted test (UFT Settings → Resources → Libraries) — the same in both conversion paths, differing only in where the shared .pfl lives:

  • ALM project conversion — the .pfl is created as an ALM Test Resource of type "Function library" in the same Resources folder as the source .qfl (convert-in-place) and linked by its [QC-RESOURCE] path.
  • Local filesystem conversion — the .pfl is written once to a shared FunctionLibraries/ directory beside the converted tests and linked by its on-disk path. That path is stored absolute, and cross-test shareable action references are likewise rebuilt against the callee's absolute published action folder — so the converted tree is not relocatable: run it from the output root it was written to, or re-run the conversion with the final location as --output-root. Every such binding is listed in the "Portability Manifest" section of convert_report.html.
  • Libraries linked from outside the source roots are converted but not analyzed. Design-time library linkage lives in the binary Test.tsp and is readable only through the AOM, so the analysis (which reads the source roots from disk) cannot see it: a library a test links from a folder outside every source root gets no inventory entry, no planned-transformation row and no blocker assessment, while the conversion still converts and links it. Add the folder holding the linked libraries to the source roots and re-run the analysis to have them assessed. A linked library missing from disk blocks its own test at every strictness.
  • Keep shared libraries out of test folders under Convert Mode = in-place. In-place publishing replaces each test directory; what happens to the original is the Overwrite Policy's decision. Under backup — which is also what the default fail becomes in in-place mode, since it would otherwise refuse every test — the directory is renamed to <name>.bak; under overwrite it is replaced outright. Either way every non-test file inside it goes with it, including a .qfl stored under the test folder. Phoenix links the already-converted .pfl it produced from that library so the other tests still convert, but the library is not re-translated on later runs (its source is gone), so a converter fix cannot reach it. Store shared libraries in a folder no test publishes over, or convert with Convert Mode = new.

At run time UFT loads the linked .pfl into every action's namespace, so its functions resolve directly, with no import, and can use the UFT runtime objects (Reporter, SystemUtil, …). Libraries are linked, not inlined: the library is converted once and every referencing test links the same shared .pfl, exactly like native UFT .qfl behavior. Library procedures are never copied into each action's Script.pts.

VBScript compatibility helpers live in PhoenixVBRuntime.pfl

Converted scripts need Python versions of VBScript built-ins (Right, InStr, CDate, Err, MsgBox, …). Phoenix writes those helpers once, to a shared function library named PhoenixVBRuntime.pfl, instead of pasting a copy into every action and every converted library. Each script that uses them carries a short generated block marked # _phoenix_vb_runtime that lists the helpers it needs. The block sits at the top of the script, or directly after the # _phoenix_library_binding block when the test links a function library.

  • Where it lives. ALM project conversion: an ALM "Function library" resource in the Resources child folder UFT Phoenix, created by the first conversion that needs it, linked to every converted test whose scripts use it — or that calls an action whose scripts use it — and related to that test so Test Lab delivers it. Local filesystem conversion: FunctionLibraries/PhoenixVBRuntime.pfl beside the converted libraries, linked by absolute path and listed in the Portability Manifest.
  • What runs is unchanged. The block installs the same helper text into the script's own namespace, in the same order, at the point where the pasted copy ran — after any linked function library — so a function in a customer library that shares a helper's name behaves exactly as before. A helper the converter altered inside a particular script stays pasted in that script.
  • The file only grows. Each helper entry is named with a digest of its text, and conversion only ever adds entries. A test converted by an earlier Phoenix version keeps running the exact helper text it was converted with.
  • On the filesystem path, Overwrite Policy can stop it growing. With Convert Mode new and Overwrite Policy fail (the default), the file is never rewritten. So if a later conversion into the same output root needs helper entries the existing FunctionLibraries\PhoenixVBRuntime.pfl lacks — typically after upgrading Phoenix — or finds one of its entries edited, each such test is blocked with "shared function library … already exists with different content and overwrite policy is 'fail'". Use backup or overwrite for that run (existing entries are kept, so tests converted earlier are unaffected), or convert into a new output root.
  • Do not edit it. A converted script runs whatever text the file holds under the names it lists, so an edit takes effect on the next run. The next conversion that writes the file checks every entry against its digest: an edited entry for a helper the current version still has is put back to its original text, and an edited entry for an older helper is dropped, after which scripts that name it stop with the error described in troubleshooting.md. ALM conversion reports such a rewrite as replaced content and keeps the prior copy; a filesystem conversion needs Overwrite Policy backup or overwrite to rewrite the file at all.
  • Analysis writes nothing. Standard and deep analysis leave the helpers pasted in what they build, and create no library.
  • Report line counts still include the helpers. "Python lines produced" and "Changed Lines" measure the converter's output, which is produced before the helpers move into the library.
  • Mixed projects are fine. A script converted by a Phoenix build that predates PhoenixVBRuntime.pfl — recognizable by pasted helper definitions and no # _phoenix_vb_runtime block — keeps its pasted helpers until it is converted again; both forms run side by side.
  • A converted library already on the server keeps its pasted helpers. If the existing copy of a converted function library still carries pasted helpers, tests outside the current conversion may load it without being related to PhoenixVBRuntime.pfl, so conversion rewrites it with its helpers pasted. Only a library that is new, or already uses the runtime library, is written without them. To remove the pasted helpers from such a library, delete its converted .pfl resource and convert the whole project again.
  • If the runtime library is unavailable, nothing breaks. ALM conversion relates PhoenixVBRuntime.pfl to a test before any of its scripts depend on it. If the library cannot be written, read or related, that test keeps its helpers pasted and converts exactly as before, and the conversion notes say "helpers stay pasted". A test fails only when something it links is already compacted on the server and cannot fall back.

Measured on the reference test set: a whole-project conversion moved the helpers of 45 tests into the runtime library and related it to 6 more that call actions using it; all 51 were then run in Test Lab. None failed on the library or a missing helper. The approved regression set of 81 tests, 31 of which use the runtime library, passed with the same status and the same checkpoint count as its VBScript baseline.

Every converted action other than the main flow that uses a linked function library starts with a generated block marked # _phoenix_library_binding, which loads the library itself on every iteration (the reason is in supported_versions.md). In an ALM conversion the main flow instead gets a # _phoenix_library_scope block, which tells the actions it runs which library to load.

Both blocks record the library the test was linked to when it was converted: its ALM resource ID (for example _phx_want = '<resource id>') and its file name, or, for a filesystem conversion, its absolute path. The values come from each test's own links — they are not built into Phoenix — but they are written into the script as literals. Nothing updates them when a library link changes afterwards.

Changing the content of the linked library is safe: its resource ID and path stay the same, so the block loads the new content. Changing which library is linked is not. The block keeps loading the originally linked library for as long as a copy of it can be found — in an ALM run, in UFT's extraction cache on the execution host (%LOCALAPPDATA%\Temp\TD_80); for a filesystem conversion, at its original path. It loads that library after UFT has bound the new one, so the old library's functions replace any with the same name. No step fails and nothing is reported.

After conversion, you… The converted test…
edit or replace the content of the linked library runs the new content. Not affected.
link a different library with the same file name (for example, a copy from another folder) runs the old library if a copy of it is in the cache — left by an earlier run, or extracted in the same run for another test that still links it. If none is, it uses the new library when that is the only one of that name in the cache, and otherwise leaves the choice to UFT.
link a library with a different file name, or add a second library does not load the new library itself, so it has the problem the block exists to fix: in a multi-test Test Lab session the new library's functions can be missing from the second iteration onward. If a copy of the old library is still found, that is loaded too and its same-named functions win.
remove the link still loads the old library while a copy can be found, which hides the removal.

For a filesystem conversion the rule is simpler: the old library is loaded whenever its file still exists at the original path.

Relinking a test that calls other tests' actions changes those actions too: when run from that test, they load the library its main flow names.

Editing the generated lines by hand does not fix this. An action's own _phx_want is overridden by the ID the main flow publishes, and the next conversion rewrites both blocks.

Workaround:

  1. Change library content, not links, where you can. To give converted tests different library code, update the library they already link: upload new content into the same ALM Function library resource, or overwrite the same .pfl on disk. Leave the _phoenix_lib_marker__… function at the end of the library in place; the block uses it to recognize the right library when it has to search by file name.
  2. If a link must change, convert again afterwards. Conversion removes both generated blocks and writes them again from the test's links at that moment.
  3. ALM: Phoenix reads a test's links from its ALM resource relations (the Test Resources the test uses). Before you convert, check in ALM that the relation names the new library.
  4. ALM: conversion is whole-project and needs a current analysis in the same run folder, so choose a new run ID and run the analysis under it first, then convert. In the GUI, change Analysis Run ID on Step 5 — it defaults to <Domain>-<Project>, the same value on every run; on the CLI, pass --run-id. A conversion under an earlier run's ID resumes that run — it continues the run's conversion wave if that is unfinished — and skips every test it already converted that is still Python on the server, including the test you relinked, and re-running the analysis under that same ID does not clear the record. If a pasted copy was converted while its original was parked or converted differently, first copy alm_aom_work\alm_rollback\pasted_copy_owner_maps.json from the earlier run folder to the same place in the new one (ALM environment boundaries, below).
  5. ALM, if a resumed run stops on a cross-test reference: a test carried forward from an interrupted run still serves as a callee, so its callers convert as usual. The exception is a run folder whose journal an earlier version of Phoenix wrote, before the converted action layout was recorded: a caller of a test carried forward from it is blocked with "cross-test reference … that callee has no conversion record in this run", and the callee's entry in alm_aom_results.json shows resumed: true and a note that its journal record carries no conversion maps. Re-running the conversion in that run folder cannot get past it and re-running Analysis there does not help; start over under a new run ID as above. The same message also appears when a callee failed or was not converted in the run; see troubleshooting.md. Keep the old run folder — the snapshots in its alm_aom_work\alm_rollback directory are the only pre-conversion originals of the tests converted before the interruption. That directory also holds pasted_copy_owner_maps.json: copy it to the same place in the new run folder first if a pasted copy was converted while its original was parked or converted differently.
  6. Filesystem: convert the test again; its links are read through UFT.
  7. Clear the cache on every execution host before the next run, using the command in advanced_troubleshooting.md §1c, so no old copy is left to find. On its own this is not enough if another test in the same run still links the old library, because UFT extracts it again for that test.

ALM environment boundaries

  • How UFT runs a converted pasted copy has not been measured yet. A test whose stored Download.xml names another test (an ALM copy/paste) converts like any other test when ALM gave the copy its own asset records (Phoenix checks this): it is converted from those records, its notes name the test it was copied from, and the scan report counts it under Pasted copies. On the one ALM server measured, all 230 pasted copies had records of their own. Phoenix leaves the copy's stored Download.xml, which still names the original, as the paste left it, and no live run has yet shown how UFT runs the converted copy. Until one has, convert a pasted copy together with its original: do not park one of them while the other converts.
  • A pasted copy converted without its original depends on its first-sight record. The first analysis or conversion in a run folder that sees a pasted copy records, by record id, which of the copy's asset records stands for each entry in its manifest, in alm_aom_work\alm_rollback\pasted_copy_owner_maps.json. A conversion renames a copy's action record when the rebuild moves the action to another folder, and a restore does not rename it back. In a run folder that does not hold the file — a new run ID, or a folder the file was deleted from — Phoenix still recognizes a copy converted with its original: it pairs the copy's records with the original's, which that conversion renamed alike, unless two action records of either test share a description. A copy converted while its original was parked or converted differently, or one whose action records share a description, has only the file to tie it to its manifest: without it the copy is refused as shared-assets, which stops the whole conversion, and a restore that cannot place every one of its action records fails. Keep the file with the rollback snapshots, and before you analyze such a copy in another run folder, copy the file to the same place there.
  • Tests that do not own matching asset records are refused (shared-assets, no override): a test that owns no asset records of its own, or whose records do not match its manifest. The error names the other test. Re-creating the test so it owns its records gives it a new test id, which leaves its Test Lab history with the old one. See advanced_troubleshooting.md §1a.
  • A caller left out by a path filter is not checked. An analysis reads which tests each test in Out-of-scope test IDs (--alm-exclude-test-id) calls, and the conversion refuses to turn a test one of them calls into Python (parked-caller). A test that Path Exclusions leaves out (or a CLI --include pattern it does not match) is never downloaded, so its calls are seen only when the analysis it is judged on measured it — a test moved into an excluded folder since, for example. Keep call chains whole when you write path filters.
  • A parked test's stale call refuses every test of its name. When a parked test (in Out-of-scope test IDs, or path-excluded and measured by the analysis) calls a test by a path no test has any more — the test it called moved or was renamed — and the name matches more than one test, the conversion cannot tell which one the call means. It refuses each of them it would convert (parked-caller), with the tests that call them, rather than guess. In a project with several same-named tests one such call can hold back all of them until the call is fixed in ALM to name its test by full path and the analysis is re-run.
  • A parked test whose definition ALM cannot give blocks the conversion. If the analysis cannot read which tests a parked test calls, the conversion refuses it (parked-references-unread) after every analysis, and the analysis report lists it as needing manual intervention. The Migration Console has no override: delete the test in ALM if it is no longer used, or bring it back into scope and fix it there (remediation.md).
  • Libraries attached only through Test Settings (no ALM resource link) with bare function calls are not detectable — verify library linkage in ALM before migrating.
  • OTA entity contracts vary by ALM deployment and patch level; site-specific behaviors encountered so far are cataloged in advanced_troubleshooting.md §6.
  • UFT API/Service tests (C#-based) are inventoried and skipped; conversion coverage is GUI/script assets.

Free edition

The free edition converts an ALM project, or the tests under the source folders of one filesystem run, of up to 100 test cases; the analysis has no limit. licensing.md has the rules. What to know before you plan:

  • The count is taken before any exclusion. Parking, Path Exclusions and Path Inclusions narrow what a run converts, not the count, with one exception on disk: tests under folders named out, .git or __pycache__, which the default Path Exclusions leave out, count only when the run's Path Inclusions and Path Exclusions keep them. On the ALM path the count is always the whole project.
  • API tests stored as GUI tests count. ALM can store a UFT API test with the GUI type QUICKTEST_TEST. Phoenix tells such a test apart only after it downloads it, so it counts toward the limit, although Phoenix never converts it.
  • The count can be higher than Assets in Scope, which leaves out parked, excluded and API tests.
  • Deleted tests never count, and never convert. Tests inside a .TrashCan or Recycle Bin folder, at any level within the ALM project or below a run's source folders, are left out of the count, the analysis and the conversion on both paths, and no option brings them back. On disk, publishing still protects them: a test whose folder, or whose destination, holds such a folder with a test in it is blocked until you move that folder out (usage.md § Taking tests out of scope, and where the drops are reported).
  • Over the limit, a Deep analysis keeps no builds. It deletes each test's converted build once it is checked and measured, so Compare Converted Output… and anything else that reads alm_aom_work\test_<id>_build\ needs a license, or a project of up to 100 test cases.
  • A pilot of a larger conversion needs a license too. Whatever your reason, test cases you copy or move out of a project or folder still count toward any conversion of it, and separate runs on folders that share a parent folder count as one conversion of that parent folder (license agreement, section 2.g). Phoenix counts one run at a time and cannot see that; the agreement still applies.
  • A license is installed from the command line or by the installer. The Migration Console shows the edition but has no license field. A license installed for one Windows user does not apply to another; install it with --all-users to serve every user of the machine.
  • A license that names ALM projects lifts the limit for those projects only, by the server names it lists; on disk Phoenix cannot tell where a folder of tests came from, so a filesystem run accepts any valid license.
  • Expiry is checked against this machine's clock. There is no online check, so the license applies through the end of its expiry day as this machine counts it.

Asset locks

A lock never fails a conversion — locked assets are converted and overwritten, and there is no locked failure status on the conversion path. This is safe because an ALM lock does not block ExtendedStorage.Save, the write that carries a test's payload (Script.pts, Test.tsp, the .usr); it blocks only entity metadata writes (SetField/Post), which the upload path already treats as optional. Per asset the pipeline allows a 10-second grace period for the lock to clear on its own, attempts to release it, then converts either way. It has to: a whole-project ALM conversion is all-or-nothing, and a run that dies partway leaves the project half Python and half VBScript, breaking cross-test action chains and poisoning every later conversion.

The limitation is in the release, not the conversion. UnLockObject() releases only your own lock — against another session's it returns cleanly and silently does nothing, so the pipeline never trusts it and always re-probes. Revoking a foreign lock means deleting its row from the project's LOCKS table through the OTA Command object, which ALM disables by default — most customers will not have it. Where it is unavailable the conversion still completes and overwrites. The run records entity-lock-force-revoked (revoked) or entity-lock-not-cleared-proceeding (overwrote anyway), and each affected asset carries a note naming the holder. The machine, ALM session id, lock time and last-active time appear only where the LOCKS table is readable through the OTA Command object — the same surface the revoke needs; without it the note names the user alone.

Overwriting takes the work of anyone still editing a locked asset, and their ALM client may hold a stale copy afterwards — run conversions in an agreed window with the project empty. See alm_safety.md § The safety model, item 9 (locks), for the full policy.

Scanner risk flags (review, not blockers)

Local filesystem analysis only. Its scan flags elevated-risk feature areas for human review: Keyword View dependencies, Active Screen dependencies, recovery scenarios, Business Process Testing indicators, and interactive input methods. These are warnings; they do not change the verdict. ALM project analysis raises none of them, and the recovery flag in particular fires only when a script line names a .qrs file and contains the word recovery — see the recovery entry above.

Supported Windows COM and WMI patterns

CreateObject/GetObject convert through a case-insensitive COM dispatch wrapper. Validated patterns:

  • GetObject("winmgmts:"), InstancesOf("Win32_Process"), ExecQuery(...), For Each over WMI collections, Process.Name, Process.ProcessId, collection .count, objProcess.Terminate()
  • StrComp(left, right, vbBinaryCompare|vbTextCompare)

More complex WMI namespaces or broader COM object models should be reviewed during sign-off.

FileSystemObject coverage and restrictions

CreateObject("Scripting.FileSystemObject") converts to a COM-backed Python equivalent. The converter handles the FileSystemObject and TextStream members explicitly, including OpenTextFile, CreateTextFile, OpenAsTextStream, Read, ReadAll, ReadLine, Skip, SkipLine, Write, WriteLine, WriteBlankLines, Close, FileExists, FolderExists, CreateFolder, DeleteFile, DeleteFolder, CopyFile, CopyFolder, MoveFile, MoveFolder, GetFile, GetFolder, GetSpecialFolder, BuildPath, GetTempName and GetAbsolutePathName.

Restrictions: - Local Windows filesystem semantics are assumed; UNC, locked-file, and permission-sensitive flows need runtime validation. - Encoding, sharing, and line-ending behavior should be validated for scripts depending on non-default text handling. - The property-heavy object graphs GetFile/GetFolder return, binary workflows, stream seeking, and ADODB-based file handling remain outside the qualified path: they convert, but no run has validated them.

OptionalStep handling

OptionalStep.<object>.<action> converts to an existence guard around the action — if <object>.exist(): <action> — with an else branch that reports "Optional step skipped" as an informational (micDone) node, so a skipped optional step still leaves evidence in the run report.

exist() is called with no argument, which waits the test's object synchronization timeout — the same wait VBScript's OptionalStep performs. This matters: an optional step is commonly used to dismiss a dialog or click a control that takes a moment to render, and the step is meant to run if the object turns up inside that window. An instantaneous exist(0) probe would skip it and still pass, turning a wait-then-act step into a silent no-op. Earlier Phoenix builds emitted exist(0), and a test converted by one of them keeps it: re-converting a test preserves an action that is already Python as it stands. To find them, search converted action scripts for .exist(0): followed by an else branch that reports "Optional step skipped". To fix one, change .exist(0) to .exist() in the script, or restore the test to VBScript (uft-migrate restore, see alm_safety.md) and convert it again; a filesystem conversion can simply be run again from the VBScript source. In the reference test set the affected tests finished in 1–9 s against 22–26 s under VBScript, the difference being exactly the wait that had been dropped.

Runtime parity

  • Local UFT execution is not a Phoenix feature. --run-uft was removed when the AOM conversion path became canonical. The flag is still accepted purely so it can be refused by name — it fails the command (exit 2) rather than silently running nothing. To check a converted test locally, open it in UFT One and run it by hand.
  • ALM Test Lab execution (CLI-only support tooling, --run-via-alm; the GUI never runs Test Lab) requires an active interactive desktop session on the execution host (GUI identification fails on locked/disconnected sessions) and report artifacts can vary by ALM/UFT patch level.
  • A "Passed" Test Lab run whose report is missing expected actions is flagged incomplete-execution rather than trusted.

Conversion can surface object-identification failures your baseline hid

This is the one result most likely to be mistaken for a regression, so read it before you compare a converted run against its baseline.

A test whose object descriptors no longer match the application can pass under VBScript and fail after conversion, having changed in no other way. The failure is not introduced by the conversion — it was already there, graded as a warning.

Measured on the reference test set, three tests failed after conversion against an 84/84 VBScript baseline. Their baseline runs look like this next to their passing near-duplicates:

Duration Final step Graded
the three affected tests 24–27 s Replay Warning Passed
their passing twins 2–4 s Verification Passed

24–27 seconds is the object sync timeout (ObjectSyncTimeOut, 20,000 ms by default) plus overhead. Those runs sat waiting for an object they could not find, gave up, logged a Replay Warning — and UFT still graded the run Passed. After conversion the same condition is booked as a Replay Error, which fails the run. The underlying cause was stale identification data: the tests carried vendor-era window titles that no longer match the installed application.

How to find these before you convert. In your baseline results, look for runs whose duration is at or just above your object sync timeout and whose step list ends in a Replay Warning on a step that is not an OptionalStep, with no checkpoint or verification step. A test that genuinely exercises its application finishes far faster and books a real verification. Fix the descriptors first and your baseline becomes a true baseline.

Do not over-read this. It is not a general rule that the Python engine is stricter. Other tests in the same project logged a Replay Warning at a similar duration under VBScript and still passed after conversion. Those warnings came from OptionalStep lines: under VBScript a skipped optional step is recorded as a Replay Warning after the sync timeout has been waited out, which is intended behavior (see OptionalStep handling above). The tests that failed logged their Replay Warning on a mandatory step. The grading difference itself is UFT engine behavior that Phoenix does not control; what is actionable is the detection method above.

A source helper that scans every process runs slower after conversion

A VBScript helper that walks the whole process table — a "close process by name" helper that calls GetObject("winmgmts:").InstancesOf("Win32_Process") and reads .Name on every returned object — adds seconds to every call once converted. Nothing fails and no step result changes; the run is simply slower.

Measured on the reference test set, the same 84 tests on the same host, VBScript baseline against the converted tests: the six tests that call such a helper once or twice each ran 6–15 s slower per run (+15 s, +12 s, +10 s, +8 s, +7 s, +6 s), roughly 4–12 s per call, where their whole VBScript runs took 1–8 s. The added time sits between the run's Start Action node and its first reported step, and the cost grows with the number of processes on the machine.

Two controls locate the cost in the loop rather than anywhere else: tests that link the same function library but never call the helper showed no change (so it is not library loading), and tests calling a sibling copy of the helper that asks WMI for the process by name — ExecQuery("Select ... from Win32_Process where Name = '<exe>'") — showed no change either. The cost therefore sits in the enumeration: one property read across a COM boundary for every process on the machine.

The conversion is faithful: it carries whichever form the source library has. If the run time matters, change the source helper to the filtered query before converting, and the cost disappears.

Run time on UFT 26.1 and 26.3

The same 81 tests, the same host, final runs: the VBScript originals took 979 s, the converted tests 1,076 s on UFT 26.1 and 1,149 s on UFT 26.3. Most of the difference from VBScript is the process-scanning helper above. On short tests UFT 26.3 adds about 0.6 s per test over 26.1; the cause is not isolated.

A failing step ends the action

When a step fails in a converted test — its object cannot be found, say — UFT's Python engine raises an error and the action stops at that line. The run report shows one Replay Error and a Run Error traceback naming the line. The VBScript original, run the same way from Test Lab, reported the failure and carried on, so every later step that depended on the missing object failed and was reported too. The verdict is the same, Failed; the converted report is shorter and the failed run faster. Measured on the reference test set: a login test whose window was missing failed in 22 s after conversion, with one failed step reported, and in 106 s before, with four.

Steps that pass are unaffected. But the steps after a failure, in that action, no longer run: if the source relied on them — closing an application at the end of the action, for example — the next test can find that application still open.

Version-controlled ALM projects

Version-control support is implemented and needs no configuration: versioning is detected automatically per asset; a pre-existing checkout — another user's, or a stale one of ours — is undone first, reverting the server working copy to the latest checked-in version (which is what gets converted); check-in happens only after post-upload verification passes; any failure after check-out abandons the checkout so the server keeps its last checked-in version; and Python function-library resources (.pfl) are checked out and checked in too, though each is checked in as soon as its content lands — before the test's own verification — so a failed test or an abort rollback does not revert a replaced library (its previous version stays in ALM version history). Undoing another user's checkout requires the connected ALM user to hold the "Manage checkouts"-equivalent permission — without it the asset fails as "Version control blocked" (vc-blocked).

The basic path — check out, convert, verify, check in as a new version — has been run against a live version-enabled project, for tests without linked function libraries. Undoing another user's checkout, the missing-permission vc-blocked failure, abandon-on-failure, and check-out/check-in of function library (.pfl) resources including PhoenixVBRuntime.pfl have unit coverage only. Validate them on a copy of a version-enabled project before a production wave.

Crash recovery (ALM upload conversions)

A whole-project ALM upload conversion recovers from a native crash of its own process: a crash supervisor records it, keeps the evidence and starts the conversion again, and the new attempt restores any test the crash left changed from the copy the conversion wave froze before changing it (advanced_troubleshooting.md §9). Its limits:

  • Only upload conversions are supervised. An analysis (Standard or Deep), a gate rehearsal (--upload --dry-run), a filesystem conversion and the Migration Console itself are not: a native crash ends them with no result, and you run them again.
  • Recovery has a budget. The third crash while the same test is in flight, the wave's crashes reaching its crash budget, or the second crash in a row outside any test ends automatic recovery: the wave is aborted and what it wrote is rolled back (a wave with nothing to roll back is just closed), and the test in flight, if any, is reported process-crashed. It is not retried further. The wave's crash budget is 6 plus 2 % of the tests it has begun converting, rounded down (7 at 50 tests, 8 at 100, 12 at 348, 106 at 5,000). A wave an earlier version of Phoenix opened keeps a fixed budget of 6.
  • Planned restarts have a limit too. When its memory runs high, the conversion process restarts itself between two tests. That is no crash and uses no crash budget (troubleshooting.md, The conversion process restarted itself to free memory). One launch of the conversion makes at most 100 such restarts, at least 25 finished tests apart, so the limit cannot be reached below 2,500 tests in one launch. A restart needed after the 100th is not made: the conversion stops with planned-restart-limit and the wave open, and running it again with the same inputs continues it.
  • Finish an open wave with the version that opened it, or a newer one. An earlier version (1.3.0, for example) applies a fixed budget of 6 to every wave. Continued with it, a wave a newer version said it would carry on can be aborted and rolled back at its next launch. During a validation, keep each run folder on one version.
  • An interrupted rollback is not finished automatically. If the conversion process crashes or is stopped while it rolls a wave back, the wave stays open and every later conversion in that run folder stops, naming each test still to restore and its uft-migrate restore … --wave command. Run them by hand, callers first.
  • A rollback, automatic or by restore, still puts back only the test's files and action rows. A rolled-back test keeps its relation to the converted .pfl and to PhoenixVBRuntime.pfl instead of its original .qfl; replaced .pfl content, PhoenixVBRuntime.pfl entries and action owners the conversion created stay as they are (alm_safety.md § What a restore does not undo).
  • Crash recovery checks test payloads only. It does not check or repair a function-library (.pfl) or PhoenixVBRuntime.pfl write that a crashed attempt was making. The bytes each write replaced are kept per conversion wave under alm_aom_work\alm_rollback\resources\<wave>\<test id>\. Library writes leave no journal record, so an unfinished wave that replaced a library but has not written any test yet counts as one that wrote no test when a launch with other inputs closes it (its messages say wrote no test to ALM for that reason).
  • Older copies are pruned. When a new wave starts, the test and library copies of older waves that are finished and settled are deleted, except the newest one's that wrote a test; restore --wave cannot use a deleted copy. The first-sight copies (alm_rollback\test_<id>_source) are kept. Crash evidence under crash_recovery\ is kept for the newest two finished waves that wrote a test. A wave that wrote no test, such as a launch the pre-flight gate refused, counts toward neither, even if it replaced a function library: library writes are not journaled.
  • Stopping the conversion is not a crash. Cancel in the console, Ctrl+C, or a process ended from outside is never relaunched and rolls nothing back. The wave stays open: run the conversion again with the same inputs to continue it. A launch with other inputs closes it if it has not written any test, and is refused otherwise until the wave is closed with restore --abandon-wave.
  • After the console is closed and reopened, Convert Project needs a fresh Analysis before it continues an unfinished wave, as before any conversion.
  • The Windows evidence depends on the machine. Event Viewer entries and Report.wer appear where Windows Error Reporting is enabled; a crash dump only where WER LocalDumps is configured; and none of them where a just-in-time debugger is set to attach automatically.