Manual Acceptance Test Plan¶
A hands-on validation walkthrough of Merito Phoenix for UFT, ordered so each case builds
on the previous. Run it on a machine with UFT One 26.1 or 26.3, the ALM client, and an
ALM project you can snapshot/restore, hosted on OpenText Application Quality
Management (formerly Application Lifecycle Management) 24.1, 25.1 or 26.1 —
the supported server versions. Each case lists steps and pass criteria.
Artifacts referenced live under out\<run id>\ in the directory the
Migration Console or CLI was launched from (%USERPROFILE%\out\ when
started from the Start Menu shortcut). Output Root does not move them.
Run sections A–K on a pilot project, or folder of tests, of up to 100 test cases, or with a license installed that covers it: over the free edition's limit a conversion is refused, and a Deep analysis keeps no builds, which TC-17 and TC-18 read. Section L tests the limit itself.
Launch: uft-migrate-gui (GUI) and uft-migrate (CLI).
A. Environment¶
TC-01 — Environment preflight
1. Run uft-migrate doctor.
2. PASS: exit code 0 and no [FAIL] rows. Ten rows print, in order:
platform, python, pywin32, uft-installed, uft-ironpython,
alm-client, license, output-root, offline-package,
alm-connectivity.
This plan needs UFT's Python engine and the ALM client, so
uft-installed, uft-ironpython and alm-client must be [ OK ]. A
[WARN] on alm-client or uft-ironpython fails this case. If
uft-ironpython shows [ -- ], doctor could not locate the UFT install
path; confirm the IronPython runtime by hand before continuing.
license reads [ OK ], naming the free edition (Free edition · up to
100 tests. No license file is installed.) or the installed license. A
[WARN] there does not fail this case, but means that, in the free
edition, an installed license file cannot be used, that the license in
use expires within 30 days, or that Phoenix's own license key is damaged:
read its detail and its fix: line
(troubleshooting.md) before section L. With a
license in use, a file that cannot be used is named in the detail after
Other license files: and does not make the row warn.
3. PASS: [ -- ] (skipped) on the other two rows is expected.
offline-package checks a package build folder and matters only to
whoever builds the offline package; on an installed machine it is
skipped. alm-connectivity skips unless --alm-url (or
UFT_MIGRATE_ALM_URL) is supplied, which is TC-02. Any [FAIL] names
its fix; resolve it and re-run before continuing.
TC-02 — Live ALM login check
1. uft-migrate doctor --alm-url <url> --username <user> with
UFT_MIGRATE_ALM_PASSWORD set in the shell.
2. PASS: alm-connectivity reports login OK and a visible domain count.
B. Console basics¶
TC-03 — GUI launch and state persistence
1. Launch the GUI.
2. PASS: the bottom-left corner of the dark panel on the left reads
Version and the ProductVersion in <install folder>\VERSION.txt, with
nothing after the number (no · development copy), and on the line under
it the edition: Free edition · up to 100 tests, or Licensed to and the
licensee of the installed license. Both stay there on every step.
3. On Step 2 choose Upgrade ALM Project; on Step 3 fill
Output Root, ALM URL, Username and Password; close the GUI; relaunch it
and choose Upgrade ALM Project again on Step 2 (the workflow choice
is not restored, and the ALM fields stay hidden until it is made).
4. PASS: all fields restore, including the password.
5. Open out\.uft-migrate-gui-cache.json under the launch directory
(%USERPROFILE%\out\ for the Start Menu shortcut) in a text editor.
6. PASS: the alm_password value starts with dpapi: — never plaintext.
TC-04 — ALM Connect (threaded, friendly failures) 1. Step 2: choose Upgrade ALM Project. Step 3: enter a deliberately wrong ALM URL (bad host) → Connect. 2. PASS: the UI stays responsive (no freeze, no stack trace), the Connect button comes back, and one of two dialogs appears. ALM Connection Timed Out appears after about 45 s with URL/firewall guidance, typically for an address that never answers. ALM Connection Failed appears sooner, naming the URL(s) tried and the client error, typically for a host name that does not resolve. The status line reads "ALM connection timed out." or "ALM server connection failed." respectively. 3. Enter the correct URL → Connect. 4. PASS: domain/project dropdowns populate.
C. Analysis¶
TC-05 — Project analysis end-to-end 1. Step 2: choose Upgrade ALM Project. 2. Step 3: Connect, pick a domain/project (use a small pilot project with 5–10 tests; ALM conversion is whole-project, so analysis covers the whole project), and tick I confirm the ALM project database and repository backups are complete — Step 3's validator refuses Next without it, so the wizard cannot reach Step 5 with the box clear (TC-08 part (a) exercises that gate deliberately). 3. Step 5: Run Analysis; watch per-asset progress. 4. PASS: analysis completes and the Step 5 status line carries a GO or NO-GO verdict. Open Scan HTML from Analysis Reports: it shows the approval recommendation, the Assets Passed / Assets Failed / Scan Blockers / Convertible Findings counts, and a Decision Drill-down with working links to the per-asset pages (Assets in Scope, Assets Passed, Assets Failed, Scan Blockers, Convertible Findings, Timing Metrics, and Out of Scope when any asset was excluded). The CLI Output pane holds the raw log. An ALM analysis report is organized by asset, not by file.
TC-06 — Cancel and re-run 1. Start an analysis on a larger source (a bigger filesystem tree or ALM project); click Cancel mid-run. 2. PASS: the analysis process stops immediately and the UI stays responsive. The status line briefly reads "Cancel requested — stopping analysis. …" and then "Analysis failed. …", and the progress line reads "Analysis did not complete." That is the expected end state for a canceled run: the cancel kills the process, so the CLI exits without a result payload. 3. Re-run with the same Analysis Run ID and answer Yes to Resume Previous Run. 4. PASS — filesystem source: files already scanned before the cancel are not re-scanned. ALM project: analysis has no per-asset resume, so the re-run analyzes every asset again and must finish with a verdict.
D. Conversion safety rails¶
TC-07 — Step 4 policy surface and read-only analysis
1. Step 4 (Conversion Strategy): review the page.
2. PASS (Upgrade ALM Project workflow): only the ALM Conversion policy
note and the Script Preservation frame (VBS Preservation Mode:
comment-block | interleave | python-only) appear. There are no ALM
option fields — no Upload, Dry Run, blocker-override, cache-purge, or
Test Lab controls — and the Filesystem Conversion Options frame is
hidden on this workflow. (UFT FileSystem workflow: Step 4 shows
Filesystem Conversion Options — Convert Mode, Overwrite Policy
[fail | backup | overwrite], Parallel Mode (no effect) — and Script
Preservation, with no ALM Conversion note. The two frames are never
shown together.)
3. Step 5: Run Analysis over the pilot project.
4. PASS: analysis behaves as a read-only dry run — the tests' Modified
dates in ALM are unchanged. (The Step-3 backup confirmation was already
required before Analysis could be reached: it gates wizard navigation,
not the analysis run, which the GUI issues as convert --alm --dry-run
with no ALM writes.)
TC-08 — Backup confirmation gate The GUI gate and the CLI gate are different mechanisms at different points, so check both.
(a) GUI — navigation validator on Step 3. 1. Step 2: choose Upgrade ALM Project. Step 3: fill ALM URL, username, password, click Connect, pick a domain and project, and make sure I confirm the ALM project database and repository backups are complete is unchecked. The tick is never restored from the settings cache — every launch of the console starts with it clear — but it is still ticked from TC-05 if the console has stayed open since, so clear it. Press Next. 2. PASS: a "Backup Confirmation Required" modal appears, the wizard stays on Step 3, and no conversion is launched. The checkbox lives on Step 3, next to the ALM connection fields — Step 6 cannot be reached with it clear. (The earlier Step 3 checks fire first: an unfilled URL/username, no Connect, or no domain/project produces "Missing ALM Inputs" or "ALM Connection Required" instead.) 3. Tick the box and press Next. 4. PASS: the wizard advances to Step 4.
(b) CLI — refusal before any ALM write.
1. Run uft-migrate convert --alm --upload ... without
--confirm-alm-backup.
2. PASS: exit code 2 and a status: failed refusal naming
--confirm-alm-backup, raised before the ALM login, so nothing is touched
on the server. --upload is what arms the gate: adding --dry-run makes
no ALM writes and does not require the flag. Neither analysis depth lists
the files an upload would write or delete, and with --upload --dry-run
the run rehearses the gate without building any payload. (ALM conversion
from the GUI always uploads in place; there is no GUI dry-run toggle.)
TC-09 — Fail-closed blockers
Run this case as a Deep analysis: at the default Standard depth the
analysis never opens UFT, so it does not evaluate Parameter() definitions
at all — it records the note "N action(s) read Parameter(); their
definitions are harvested at conversion time (analysis does not open UFT)",
reports the asset ok, and the verdict stays GO. The blocker is raised only
by a Deep analysis or by a real conversion.
1. In the pilot project, prepare a test whose action body calls
Parameter("x") where x is defined at NEITHER action level (Action
Properties → Parameters) NOR test level (File → Settings → Parameters).
Leave the referencing action with no action-level parameters of its own,
and give the test some parameter definitions elsewhere — test-level
definitions that do not include x, or action-level parameters on a
different action. (An action that carries any action-level definitions of
its own is skipped by the resolver, so Parameter("x") there raises no
blocker and the asset reads ok — that is not a failure of this case,
it is the wrong setup for it.)
2. Step 5: set Analysis Depth = Deep and Run Analysis. Deep analysis
rebuilds each test in UFT locally and writes nothing to ALM.
3. PASS: that asset's status is blocked in alm_aom_results.json and on
the Assets Failed page; the blocker names the action and the unresolved
parameter name(s) — e.g. Action1: Parameter() references ['x'] not found
among the legacy test's action or test-level parameter definitions (it
does not cite a source line); no ALM write occurred; the verdict is NO-GO
and Step 6's Convert Project refuses to run. If instead the test carries
no parameter definitions at all, the blocker is the variant Action1:
Parameter() referenced but no parameter definitions (action or test-level)
were found on the legacy test — it names the action but not x, and is an
equally valid PASS.
4. PASS (what a real conversion would do, for the approver's record): in a
whole-project upload conversion this status is fatal. The run aborts at
that asset, every asset already uploaded in the run is restored from its
pre-conversion snapshot and recorded rolled-back, and the remaining
assets are recorded not-attempted. Any asset recorded rollback-failed
is still converted on the server and must be restored with
uft-migrate restore … --wave <wave> from the copy the conversion wave
froze (the asset's wave in alm_aom_results.json) before the project
is used. restore puts back each test's own scripts and actions only — the
resource relations the conversion changed are not reverted, so a restored
VBScript test stays related to the converted .pfl and to
PhoenixVBRuntime.pfl rather than to its original .qfl. Do not leave this
test in the project — see the clean-up step before section E.
TC-09a — Test-level parameters are carried, not blocked
1. Using the same Deep analysis run, pick a test whose main flow or actions
read Parameter() names defined only at TEST level (File → Settings →
Parameters), where the reading action has no action-level parameter
definitions of its own.
2. PASS: status ok; notes show Harvested TEST-level parameter
definitions: [...], <Action>: Parameter() references satisfied by
TEST-level definitions (...), and Carrying parameter definitions:
main-flow=[...]. After TC-11's conversion, the converted test's UFT
Settings → Parameters lists the definitions with their legacy defaults.
Default values carry, but test-set runtime overrides do not propagate
through the AOM main-flow indirection. (The satisfied by TEST-level
definitions note is emitted on the ALM path; the local filesystem path
logs only Harvested TEST-level parameters: [...].)
TC-10 — A pasted copy converts from its own asset records
1. In ALM, copy/paste an existing GUI test in the pilot project's Test Plan —
one that no other test calls. Then, in UFT, open the original (not the
copy), add one step that the copy will not have —
Reporter.ReportEvent micDone, "TC-10", "original" — and save it. Re-run
Analysis (Step 5).
2. PASS: the copy's record in alm_aom_results.json is ok and its notes
name the original's test id; Scan HTML shows a Pasted copies row that
counts it; and alm_aom_work\alm_rollback\pasted_copy_owner_maps.json in
the run folder holds an entry for the copy — one for every copy that row
counts, and no copy's notes say could not be kept. The analysis wrote
nothing to ALM. If the copy shows shared-assets instead, ALM did not give it asset
records of its own that match its manifest: the refusal is correct, but
this case cannot run on that paste — record how the copy was pasted.
3. PASS, after TC-11's conversion: the copy and its original both end ok
with upload_verified ok, and the copy's notes show
owner_resolution='pasted-copy-map' on its ARI ownership sync.
4. Add the copy and its original to a Test Lab test set and run both from
ALM, with the execution host's desktop session active and its
%LOCALAPPDATA%\Temp\TD_80 purged. PASS: each run executes its converted
Python — real steps, never the line 1 ... could not be found
placeholder — and only the original's run report shows the TC-10 step,
so the copy ran its own script.
The other outcomes cannot be produced on demand, and are covered by unit tests
only: shared (the test owns no asset records) and unmatched (its records do
not match its manifest), both refused as shared-assets, and unreadable (ALM
could not return its records), which ends error and is retried.
Clean-up before section E
ALM conversion is all-or-nothing, so the test TC-09 put into the pilot project
will refuse the conversion run. TC-10's pasted copy stays: it converts in
TC-11, with its original. Before continuing:
1. Park neither TC-10's copy nor its original: until a live run has measured
how UFT runs a converted copy, a pasted copy converts together with its
original. If the copy showed shared-assets instead, delete it. It must
not be parked: a shared-assets asset is withheld from the park list
on purpose, because the test it names converts in any run that proceeds.
2. Remediate the TC-09 test (define the missing parameter at action or test
level in UFT, or replace the read with a DataTable/Environment lookup),
or park it on Step 5 under Out-of-scope test IDs. Parking leaves it
untouched in ALM and still VBScript after the migration.
3. Alternatively, restore the pilot project from its snapshot, then repeat
TC-10's steps 1 and 2 so the copy is there for TC-11.
4. Re-run Analysis until the verdict is GO. A Standard analysis will not
flag the TC-09 test, but its blocker would still abort and roll back the
conversion, so remove or remediate it either way.
TC-10a — Discovery reads the whole Test Plan, or the run stops
Run it after the clean-up, with the GO analysis.
1. Open migration_log.txt in that analysis's run folder.
2. PASS: it holds an alm-discovery-walk line, level info, for the
analysis's discovery. Its tests_seen equals the number of tests in the
project's Test Plan, of every type (the MANUAL and API tests the analysis
leaves out of scope included); tests_by_top_folder lists each top-level
Test Plan folder with the number of tests ALM shows under it;
project_check reads "status": "ok"; error is empty. There is no
alm-discovery-retried line.
3. On the pilot project, delete from the Test Plan in ALM one in-scope test
that no other test calls — not TC-10's copy or its original. Do not run
the analysis again. Run Convert Project.
4. PASS: the run is refused: Pre-flight gate FAILED … NO ALM WRITES WERE
PERFORMED, with the deleted test listed as analyzed-but-not-selected.
migration_log.txt holds one alm-discovery-retried line, level
warning, whose missing lists that test's id and whose error is empty,
and an alm-discovery-walk line for each of the conversion's two
discoveries. The other tests' Modified dates in ALM are unchanged.
5. Put the test back before TC-11: restore the pilot project from its
snapshot (then repeat TC-10's steps 1 and 2), or re-create the test and
run the analysis again until the verdict is GO.
6. Optional, with an account that one failed login does not lock: from a
Command Prompt, set UFT_MIGRATE_ALM_PASSWORD to a wrong password and run
uft-migrate run --alm --upload --confirm-alm-backup --run-id <run id> …
with that run's other inputs.
7. PASS: the run stops at once, exit code 2, with ALM discovery failed: ALM
login failed …, and migration_log.txt has no new alm-discovery-retried
line. Where your ALM site records failed logins, it holds one for the
account at that time, not two. Set the right password again.
TC-10b — A parked test keeps the tests it calls in VBScript
Run it after TC-10a, with the GO analysis, on a test that calls a shareable
action of another in-scope test and that no other test calls (the report's
dependency graph shows them) — not TC-10's copy or its original.
1. Step 5: add the calling test's ID to Out-of-scope test IDs and press
Run Analysis, with the same Analysis Run ID.
2. PASS: the CLI Output shows reading which tests 1 parked test(s) call
(read-only), then read which tests 1 of 1 parked test(s) call.
migration_log.txt holds one alm-parked-references-read line, level
info, with "parked": 1, "read": 1 and "unread": 0, and no
alm-parked-references-unread line. In alm_aom_results.json,
parked_references holds one entry for the parked test, with
"references": "read" and the called test's path in
external_test_paths. No test's Modified date in ALM changed. Record
the time between the two CLI Output lines: it is what reading one parked
test costs on this server. Scan HTML shows Conversion blocked: Step 6
refuses N in-scope test(s) that parked tests call under Tests Step 6
Refuses Because Parked Tests Call Them: the called test, with the parked
test as its caller, and every in-scope test that calls the called test.
The verdict may still read GO.
3. Run Convert Project. PASS: the run is refused: Pre-flight gate FAILED
… NO ALM WRITES WERE PERFORMED. alm_preflight.json lists the called test
as parked-caller, its detail naming the parked test, and every in-scope
test that calls the called test as callee-disqualified: the tests the
report listed in step 2, with the same details. The other tests'
Modified dates in ALM are unchanged.
4. Remove the ID from Out-of-scope test IDs and run Analysis again until
the verdict is GO before TC-11.
5. Whenever an analysis in this plan reports a failed asset that calls, or is
called by, a test that passed, check its report. PASS: the asset is not in
Park the Failed Assets, and the note under that block names it with
park only together with and the other tests' IDs; on the Failed Assets
page its row shows the same words where the Exclude checkbox would be.
6. Whenever an analysis in this plan reports a failed asset whose status is
error and you park it with Refresh Report (N parked), check the
refreshed report. PASS: Scan HTML shows Conversion blocked: … parked test
… manual intervention, with the test's name and path, why its calls were
not read and what to do, and Convert Project is refused as
parked-references-unread with nothing written. A Run Analysis with
the test still parked reads it: the section no longer lists it, or, when
ALM still cannot give the test's definition, its row says so.
E. Conversion and upload¶
TC-11 — Real conversion with verification
1. Step 6: Convert Project on the pilot project, with the GO analysis
from the clean-up step above. ALM conversion is whole-project and always
uploads in place.
2. PASS: the run completes with no failed asset — every converted asset
ends ok. (API tests and non-GUI test types are recorded out of scope
rather than converted; they are not failures.) Pick one clean VBScript
GUI test and read its record in alm_aom_results.json: upload_verified
is ok, and its notes show stale-file deletions from a server listing,
the VBScript sidecar purge, and the ARI ownership sync.
3. PASS (helper runtime), where converted actions use VBScript
compatibility helpers: the asset's runtime_helper_blocks in
alm_aom_results.json is non-empty; in ALM, Test Resources →
Resources\UFT Phoenix\PhoenixVBRuntime.pfl exists and is related to the
test. The run notes show helper runtime '…PhoenixVBRuntime.pfl'
(created) (or (helper entries added; …)) on the asset that wrote it,
and helper runtime related: … where the relation was newly made. No
asset shows helper runtime RELATION ERROR. If an asset notes
"PhoenixVBRuntime.pfl is not available to this test; its VBScript
compatibility helpers stay pasted", record why — that test keeps its
pasted helpers and still runs.
TC-11a — Conversion resume and Carried Forward
A conversion re-run into the same run folder skips assets its journal
records as uploaded and verified, provided the server still holds their
Python payload. This is what makes a long run survive an interruption.
1. With TC-11's conversion complete, click Convert Project again with
the same run ID. (The analysis that authorized TC-11 is frozen in the
run folder, so the pre-flight gate still passes.)
2. PASS: every asset TC-11 converted is skipped with the note "Already
converted: uploaded and verified by an earlier run of this scope…",
counts toward progress, and ends ok. executive_summary.html for this
run shows a Carried Forward card with that count and a matching Next
Steps note, so the document does not claim this run did the work.
3. Press Back to Step 5. PASS: Step 5 reads "Analysis verdict before the
conversion: GO … its reports are on Step 6" and does not demand a
re-analysis. (After the GUI is closed and reopened, Step 5 asks for
Analysis to be re-run before another conversion; that is expected.)
4. Optional — interrupted run. Cancel is a hard stop, not a pause: it
kills the process tree, so nothing is rolled back, any checkout the run
took is not abandoned, the end-of-run UFT cache purge never runs (purge
%LOCALAPPDATA%\Temp\TD_80 by hand before opening a converted test, or
UFT serves the pre-conversion build), UFT.exe may keep running, and the
asset that was mid-upload can be left in either state. Do not open that
asset until the conversion has been run again. On a disposable pilot
project: start Convert Project, click Cancel once at least one asset
has uploaded and confirm (a "Conversion Failed" dialog is expected), then
click Convert Project again with the same run ID and the same
selections, and answer the Resume Previous Run dialog either way — the
conversion continues the interrupted conversion wave in both cases. PASS:
if the cancel landed during an upload, migration_log.txt shows
alm-crash-reconcile-started for the asset that was in flight, then
alm-crash-reconcile-untouched or alm-crash-reconcile-restored, before
that asset is converted again; the completed assets are carried forward,
with a note that an earlier attempt of this conversion wave converted
them; the rest convert normally.
5. If the cancel in step 4 fell after a test that owns a shareable action
and before a test that calls it, PASS also requires the caller to be
converted in the resumed run rather than refused with "that callee has no
conversion record in this run": a carried-forward test still serves as a
callee, because its journal record holds the converted action layout its
callers need. The one exception is a run folder whose journal an earlier
version of Phoenix wrote, before that layout was recorded; for that folder,
run the analysis again under a new run ID and convert there. 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.
TC-12 — Asset carry-over
1. In the same conversion, pick a test with action parameters AND a linked
.qfl Test Resource.
2. PASS: notes show Harvested action parameter definitions, Carrying
parameter definitions, and that the linked .qfl was converted to a
shared Python Function Library (.pfl) and linked to the test; confirm the
.pfl resource exists in the source library's Resources folder in ALM, the
converted test's UFT Settings → Resources → Libraries lists it, and the
library functions are present as Python defs in the built .pfl (not
copied into any Action*/Script.pts). For a test that uses VBScript
compatibility helpers, Libraries lists PhoenixVBRuntime.pfl first and
the converted .pfl after it; that ordering is deliberate, because the
converted library installs its helpers from the runtime as UFT loads it.
TC-13 — Converted test opens as Python in UFT
1. Open the converted test from ALM in UFT One.
2. PASS: the test opens as a Python test; the action script is the
converted Python (not VBScript, not a placeholder); action parameters
appear in Action Properties with their legacy defaults. An action that
uses VBScript compatibility helpers carries a # _phoenix_vb_runtime v1
loader block instead of pasted helper definitions; it is the first thing
in the action unless the test links a function library, in which case
the # _phoenix_library_binding prelude comes first and the loader
follows it.
F. Execution verification¶
TC-14 — Test Lab execution (CLI-only, optional)
Test Lab execution is not available from the GUI; it survives only as the CLI
support lever --run-via-alm and its companion flags. The routine
verification path is the pipeline's own post-upload verify (TC-11), plus
opening a converted test in UFT One and running it, plus running converted
tests from their existing Test Lab sets in ALM. Run this case only when
CLI-driven execution evidence is required.
1. Use a new run ID. Re-using the earlier one makes the run read that
run's journal and skip every asset already uploaded and still Python on
the server — the skip happens before the Test Lab step, so no test would
be executed. A new run ID needs its own analysis, or the pre-flight gate
refuses the run.
2. Only for a pasted copy converted while its original was parked or
converted differently: copy
alm_aom_work\alm_rollback\pasted_copy_owner_maps.json from TC-11's run
folder into out\<new id>\alm_aom_work\alm_rollback\. TC-10's copy, which
TC-11 converted with its original, does not need it: if that conversion
renamed the copy's action records, it renamed the original's alike, and
Phoenix pairs the two. If step 3 reports the copy shared-assets, copy
the file then and analyze again.
3. Analyze into the new run folder:
uft-migrate convert --alm --dry-run --run-id <new id> --alm-url <url>
--username <user> --domain <domain> --project <project>
4. Convert and execute, with the desktop session active (do not lock or
disconnect):
uft-migrate convert --alm --upload --confirm-alm-backup --run-via-alm
--run-id <new id> --alm-url <url> --username <user> --domain <domain>
--project <project>
Conversion is whole-project, so every in-scope test gets a Test Lab run.
5. PASS: a test set is created/reused, the runs execute, and
run_results.xml under out\<new id>\alm_aom_work\test_<id>_runresults\
shows real steps — input parameters appear with values; any failure is a
genuine test/environment step, never line 1 ... previously saved ...
could not be found. A test the scheduler did not run reads No Run
with no run id and no report, even in a reused test set where it ran
before: never PASS it, and never read an earlier run of that set as its
result.
TC-14a — --run-uft refuses instead of silently running nothing
Local UFT execution was removed; the flag is kept only so it can be refused
by name on both paths.
1. Run uft-migrate convert --run-uft (no --alm) in any project folder.
2. PASS: exit code 2 and a single-line JSON {"status": "failed", "error":
"--run-uft is no longer supported: ..."} naming what to do instead. No
run folder is created under out\.
3. Run uft-migrate convert --alm --run-uft.
4. PASS: exit code 2 and the equivalent status: failed refusal, this time
naming --run-via-alm. No ALM connection is attempted.
5. FAIL if either command exits 0, or converts, or completes while ignoring
the flag.
TC-15 — Stale-cache protection (on by default)
1. Read the run notes from TC-11's conversion (and TC-14's Test Lab run, if
executed).
2. PASS: every asset's notes include "UFT test extraction cache purged
(before conversion): …" (or "UFT test extraction cache (TD_80) not present
(before conversion): nothing to purge", which is also a pass). Each asset
written to ALM also carries the "(after ALM write)" note. If TC-14 was
run, its assets also show "Purged UFT test cache before Test Lab run: …"
(or "UFT test extraction cache (TD_80) not present (before Test Lab run):
nothing to purge", which also passes).
A note that starts "[warning] UFT test extraction cache (TD_80)" also
passes this case — the purge is best-effort and always reports its
outcome — but that purge did not clear the cache on that machine. When it
is the run's last purge (the "(after ALM write)" note for a run that wrote
to ALM, otherwise the "(before conversion)" note), the Executive Summary's
Next Steps must repeat it, and you follow it (close UFT One, end
UFTRemoteAgent.exe, delete TD_80) before running TC-14; when a later
purge in the same run has no [warning], the Next Steps must not.
3. PASS: from the GUI this purge cannot be turned off — Step 4 exposes no
cache-purge checkbox. From the CLI it is on by default and only
--no-purge-uft-cache disables it; do not pass it for this case.
--purge-alm-cache / --no-purge-alm-cache are accepted but have no
effect; there is no ALM client-cache purge to verify.
4. Note for multi-host deployments: the automatic purge only covers the machine
and user running Phoenix. Every other execution host needs
%LOCALAPPDATA%\Temp\TD_80 purged by hand before it runs a converted
test.
G. Console power features¶
TC-16 — Command review is secret-free
1. Step 6: Review Command with a non-blank ALM password configured.
2. PASS: the command contains no password; a note says it travels via the
UFT_MIGRATE_ALM_PASSWORD environment variable; Copy Command works.
TC-17 — Diff viewer
Needs a project of up to 100 test cases, or a license installed that covers
it: over the free edition's limit a Deep analysis deletes each build, so
there is nothing to open.
1. Step 6: Compare Converted Output…; pick a converted Script.pts. For
an ALM run it is under
out\<run id>\alm_aom_work\test_<id>_build\<Test name>\ActionN\.
2. PASS: for a filesystem run the original VBScript usually pairs
automatically. For an ALM run it does not, so browse to the original
Script.mts under
out\<run id>\alm_aom_work\alm_rollback\test_<id>_source\ — the frozen
pre-conversion copy. Use the asset note "Action directories renumbered by
the rebuild", if present, to pick the matching action folder: Action2
in the build is not necessarily Action2 in the source.
3. PASS: changed lines are shaded, and the generated text at the top has no
left-side counterpart by design: the # _phoenix_library_binding
prelude when the test links a function library, then the
# _phoenix_vb_runtime loader when PhoenixVBRuntime.pfl is related to
the test, otherwise the pasted compatibility helpers.
TC-18 — Custom mapping rules
Custom mapping rules run against the line the converter has already turned
into Python, not against the VBScript source. Write the pattern against the
Python. Like TC-17, step 4 reads a Deep analysis's build: run it on a project
of up to 100 test cases, or with a license installed that covers it.
1. Step 3: Edit Custom Mapping Rules…; enter pattern
\bWaitSeconds\((\d+)\) and replacement Wait(\1), click Add /
Update Rule so the pair appears in the list, then click Save to
phoenix_config.json when no config file
has been selected yet).
2. PASS: an invalid regex is rejected with the parse error on Add / Update
Rule; the valid rule saves into the config file and the wizard now points
at that file.
3. Re-run a Deep analysis (or the conversion) over a test whose
VBScript contains WaitSeconds 5. A Standard analysis writes no
converted script, so there is nothing to inspect after it.
4. PASS: the built script contains Wait(5). For an ALM run, read
out\<run id>\alm_aom_work\test_<id>_build\<Test name>\<Action>\Script.pts.
(A pattern written against the VBScript form, such as
\bWaitSeconds\s+(\d+), never fires: by the time rules run the line is
already WaitSeconds(5).)
TC-19 — Failed-only re-run
Re-create TC-09's condition on one disposable test and run a fresh Deep
analysis for it. (If you are running the plan out of order, you can instead
use TC-09's own Deep analysis, before the clean-up step ahead of section E
removes that test.)
1. Confirm the Deep analysis recorded that test as failed. Depth matters: a
Standard analysis does not evaluate Parameter() definitions, so the
test would read ok and this case would prove nothing.
2. Remediate the blocked test (add the missing parameter definition at
action or test level in UFT, or replace the read with a
DataTable/Environment lookup).
3. Keep Analysis Depth = Deep on Step 5 and click Re-analyze Failed
Assets (N). CLI equivalent: convert --alm --dry-run --failed-only
--analysis-depth deep --run-id <same id> plus the usual connection
arguments and one --alm-exclude-test-id <id> for each ID in Step 5's
Out-of-scope test IDs. The button passes that field whole, and a
refresh that leaves an ID out analyzes that test too.
4. PASS: only the previously-failed assets are re-analyzed, every other
asset's result is carried forward from the previous analysis, and the
remediated test now analyzes ok. (--failed-only applies to ALM
analysis only; ALM conversion is whole-project and cannot run a subset.)
H. Reporting¶
TC-20 — Executive summary rollup
1. Open executive_summary.html from a completed conversion run (Step 6 →
Run Outputs → Executive Summary HTML). Analysis-only runs on Step 5 do
not write one.
2. PASS: it carries the approval badge ("Ready to approve conversion
program" or "Approval pending remediation") and a Readiness card
(ready/hold), and the Next Steps list matches the actual failure counts.
3. PASS: the Detail Reports links work. On an ALM run they are the scan
report, the analysis asset pages (Failed assets, All assets, Out of
scope) and, when the run wrote one, the pre-flight gate report. On a
filesystem run they are the scan, conversion and validation reports; the
ALM path does not produce convert or validation reports.
4. PASS: its Run Timing section gives the run's start, finish and elapsed
time in this computer's local time zone, with the zone and its UTC
offset, and Step 6's progress line ended with Elapsed time: close to
the same figure (the console counts from when it launched the run,
after any question it asked). On an ALM
conversion, analysis_timing.html and the scan report label the total
Total conversion time (an analysis's report labels it Total analysis
time).
I. Version control and locks¶
Run these two cases against a version-controlled ALM project.
TC-21 — Foreign checkout converts from latest checked-in version
1. Have a second user check out one test and leave uncommitted edits, then
stay connected or not (the checkout itself is what matters). Run a real
conversion (as TC-11) with an account holding the ALM "Manage
checkouts"-equivalent permission.
2. PASS: the pre-existing checkout is undone (the server reverts to the
latest checked-in version — the uncommitted edits are not converted);
the asset is freshly checked out, converted, uploaded, verified, and
checked in only after verification passes. The test ends checked in
as a new version, with prior versions intact in ALM version history (the
rollback path). Linked .pfl function-library resources go through the
same check-out/check-in cycle. At the pre-flight gate the foreign
checkout is recorded only as a warning; it does not stop the run.
3. Repeat with an account lacking that permission.
4. PASS: the conversion stops at that asset with status vc-blocked
("Version control blocked"). ALM conversion is all-or-nothing, so the run
aborts: assets already uploaded in this run are restored from their
pre-conversion snapshots (status rolled-back), the remaining assets are
recorded not-attempted, and the run reports failed. Confirm that no
asset shows rollback-failed; any that does is still converted on the
server and must be restored with uft-migrate restore … --wave <wave>
before the project is used — and, as TC-09 step 4 notes, restore does
not revert the resource relations the conversion changed.
TC-22 — Locked asset is converted and overwritten, holder named in the audit
A lock never fails a conversion. This case verifies that contract, so run it
only against disposable assets: it deliberately overwrites the work of the
session holding the lock.
1. Have another ALM session hold a lock on one test (e.g. open it from a
second ALM login and leave it open); run a real conversion (as TC-11).
2. PASS: the pipeline allows a 10-second grace period, attempts to release
the lock, and then converts the asset either way — it uploads and passes
post-upload verification like any other test, and ends ok. The run does
not fail, and no asset carries a locked status (there is no longer one).
Other assets are unaffected.
3. Read that asset's notes in alm_aom_results.json and the run log.
4. PASS: the run recorded either entity-lock-force-revoked — the lock's
row was deleted from the project's LOCKS table through the OTA
Command object — or entity-lock-not-cleared-proceeding, where that
object is unavailable (ALM disables it by default, so this is the
expected outcome at most sites). How much the note can say depends on
which path ran: the machine, ALM session id, lock time and last-active
time come from the LOCKS table, so they appear only when that table was
readable — normally the force-revoked path. On the not-cleared path the
note names only the holding user, taken from the entity's own lock owner,
or reads "holder unknown" when ALM does not expose one. The two paths word
the outcome differently: on the not-cleared path the note adds that the
asset was converted and overwritten anyway because the file upload is not
lock-gated, and that ALM refused only entity metadata writes; on the
force-revoked path it records that the lock was revoked so the asset could
be converted. Either way the asset ends ok and the overwrite stands.
5. Back in the holding ALM session, close and reopen the test.
6. PASS: the test is the converted Python version — the holder's
in-progress edit was overwritten, and their client was holding a stale
copy until reopened. This is why conversions run in an agreed window
with the project empty.
J. Crash recovery (validation runs only)¶
Run these cases only on a disposable pilot project, and only to validate crash recovery. TC-24 and TC-25 use a test-only switch that makes the conversion process crash on purpose. It is not a product feature: never set it for a real conversion, and unset it as soon as the validation run ends.
The switch is two environment variables, read by the process that starts the
conversion. Set them in a Command Prompt, then start the CLI — or the
Migration Console, from its install folder's bin\uft-migrate-gui.cmd — from
that same prompt, after cd /d "%USERPROFILE%" so the console uses its usual
run folders:
set UFT_MIGRATE_TEST_FORCE_CRASH=<test id>@<step>
set UFT_MIGRATE_TEST_FORCE_CRASH_CONFIRM=<run id>
<step> is after-intent (before any ALM work for that test),
before-upload (after the test is built, before its upload starts) or
after-first-delete (just after the upload deleted the test's first server
file, so the test is half-written). <run id> is this conversion's run id —
in the console, the Analysis Run ID. The crash fires at most once per
conversion wave, so the relaunch converts the test normally. The switch cannot
exercise the crash budget, which needs the same test to crash three times; the
budget and the abort it triggers are covered by the automated test suite only.
TC-23 — The switch cannot fire by accident
1. Set only UFT_MIGRATE_TEST_FORCE_CRASH=<test id>@after-intent — no
confirmation — and start the conversion (Convert Project, or uft-migrate
run --alm --upload --confirm-alm-backup --run-id <run id> …).
2. PASS: the conversion is refused before it starts: the result says the
confirmation does not equal this run's id, the exit code is 2, and nothing
is written to ALM (the tests' Modified dates are unchanged).
3. Set the confirmation too, and name a test that links a function library
of its own (a .qfl converted to a .pfl), with step before-upload.
4. PASS: refused again, naming the linked library as the reason and offering
after-intent; nothing is written. A test id outside the analyzed scope is
refused the same way. A test whose only library is the shared
PhoenixVBRuntime.pfl is not refused for that reason.
TC-24 — A crash before any ALM write is recovered, with evidence
1. Set the switch to <test id>@after-intent for a test, with the
confirmation, and run Convert Project.
2. PASS (while it runs): the status line first says TEST SWITCH ARMED,
naming the test and the step; then that the conversion process crashed
(0xC0000409), as the test switch's deliberate crash, while converting
that test; then the cleanup; then the relaunch.
3. PASS (at the end): Conversion Complete says one crash was recovered and
that it was the test switch's deliberate crash; every asset ends ok —
those converted before the crash are carried forward (resumed: true),
and the rest, the crashed test included, show upload_verified ok; the
crashed test's record in alm_aom_results.json carries a
[crash recovery] note saying the crash was forced by the test switch; the
executive summary's Next Steps say one crash was relaunched automatically,
that it was deliberate, with a reminder to unset the switch, and name the
crash_recovery folder of the wave.
4. PASS (evidence, in the run folder): crash_recovery\<wave>\attempt_01\
holds crash.json with "forced": true, stdout.log, stderr.log and a
command.txt with no password in it; attempt_02\command.txt does not
list UFT_MIGRATE_FORCE_CRASH_ARMED among the variables the supervisor
set, because the relaunch is never armed; the last line the crashed process
wrote to crash_breadcrumbs.log names the step
TEST: forced crash (after-intent); where Windows Error Reporting is
enabled, attempt_01\Report.wer exists and Event Viewer (Windows Logs >
Application) shows events 1000 and 1001 for that time. No crash dump
(.dmp) is anywhere in the run folder. The last [Phoenix crash
supervisor] line of the run's stderr (run_cli_stderr.log for the
console) reads TEST SWITCH STILL SET.
5. Unset both variables.
TC-25 — A half-written test is restored before it is converted again
Pick a test that links no function library of its own (the shared
PhoenixVBRuntime.pfl is fine), on a project without version control: the
switch refuses this step otherwise.
1. Set the switch to <test id>@after-first-delete, with the confirmation,
and run Convert Project.
2. PASS: before the relaunch converts anything, migration_log.txt shows
alm-crash-reconcile-started and then alm-crash-reconcile-restored for
that test — the crash had deleted one of its files, so the server no longer
matched the copy the wave froze — and resume\alm_test_results.ndjson
holds a restore-started and a restore-done record with reason
reconcile for it.
3. PASS: the test is then converted again and ends ok with
upload_verified ok; its notes carry a [crash recovery] line saying the
wave's pre-conversion copy was restored before it was converted again; the
run completes with no rollback.
4. Unset both variables.
TC-26 — One Phoenix process per run folder
1. Start Convert Project. While it runs, start an analysis into the same run
folder from a Command Prompt opened in the folder the console runs from
(your profile folder for the Start Menu shortcut): uft-migrate convert
--alm --dry-run --run-id <same run id> ….
2. PASS: the analysis exits 2 at once, saying another Phoenix process is
working in that run folder and that nothing was written; the conversion
carries on unaffected. uft-migrate restore --from-run <same run id> … is
refused the same way while the conversion runs.
3. While the conversion still runs, open a second Migration Console from the
same folder, set the same Analysis Run ID and press Run Analysis.
4. PASS: a Run Folder In Use dialog names the running process; the run
folder's reports and *_cli logs are unchanged, and the conversion
carries on unaffected.
TC-27 — An unfinished wave continues only with the same command line
1. Start an upload conversion from a Command Prompt (uft-migrate run --alm
--upload --confirm-alm-backup --run-id <run id> …) and press Ctrl+C once at
least one asset has converted.
2. PASS: the result says the run was interrupted and that the conversion wave
stays open; nothing is rolled back.
3. Run the same command with one option added, for example
--alm-exclude-test-id <a test id>.
4. PASS: refused before anything is written, exit code 2. The message says
which options differ from the wave's (added: --alm-exclude-test-id …)
and gives the complete uft-migrate restore … --abandon-wave <wave>
command, with --output-root written out — or, when the interruption left
a test half-written, says the wave is not settled and lists one numbered
restore --wave command per test, callers first.
5. Run the original command again, with or without --resume.
6. PASS: it continues the wave — migration_log.txt shows
alm-preflight-skipped-wave-resume, and alm_preflight.json holds the
gate report the wave started under — the assets converted before the
interruption are carried forward, and the run completes.
7. Optional — a wave that has written no test. On a pilot project that is still
VBScript (before step 1, or after restoring it), in a run folder of its own
(a new run id, analyzed first): start the conversion, press Ctrl+C before
the first asset's upload begins — while the run folder's
crash_breadcrumbs.log holds no upload: line — then run the same command
with one option added. After a restore with uft-migrate restore, the new
run folder recognizes TC-10's pasted copy if it was converted with its
original; if it was converted while its original was parked or converted
differently, copy alm_aom_work\alm_rollback\pasted_copy_owner_maps.json
from the run folder that converted it to the same place in the new one
before that analysis.
8. PASS: not refused: the interrupted wave is closed — a [Phoenix crash
supervisor] line and the warning alm-crash-wave-superseded in
migration_log.txt say it wrote no test to ALM and was closed — and the
conversion starts a new wave.
K. Diagnostics¶
TC-28 — Collect diagnostics
1. Run a conversion of this plan that fails — TC-21 step 3's vc-blocked
conversion — and, before you answer its Conversion Failed dialog, note
the run folder's file times.
2. PASS: the dialog shows the failure and ends with the question Collect
diagnostics for Merito support now? Phoenix saves a zip on this PC and
opens its folder. Nothing is sent. Answer Yes. (After a run that did
not fail, such as TC-24's recovered crash, press Collect Diagnostics…,
bottom left in the Migration Console beside Back, instead.)
3. PASS: when the run left crash dumps or failed tests, one question asks
whether to save them to a SEPARATE file; answer No. With neither, no
question appears. Collect Diagnostics… reads Collecting… while it
runs, then Diagnostics Saved names
out\_support\UFTPhoenix-diagnostics-<version>-<time>.zip and its size,
says nothing was sent, and the folder opens.
4. Open the folder beside the zip.
5. PASS: it holds README.txt, MANIFEST.json, TRIAGE.md, environment\,
logs\ and run\run-1\. No alm_aom_work folder, no .mts, .pts,
.qfl, .pfl, .tsr, .xls, .xlsx or .dmp file is anywhere in it;
the ALM project and test names appear as tokens (project-1,
test-…); TRIAGE.md names the run's failure. The run folder's file times
are unchanged.
6. Close the Migration Console. Start Start Menu > Merito > Merito Phoenix
for UFT Collect Diagnostics (typing collect diagnostics in Start search
finds it).
7. PASS: no Migration Console opens. When step 3 asked its question, the same
question appears; answer No. A small window reads Collecting
diagnostics for Merito support…, with nothing to press, and closing it
does not stop the collection; it goes by itself. Diagnostics Saved then
names a second zip in the same out\_support\ folder, under your profile,
says nothing was sent, and the folder opens. The run folder's file times
are still unchanged.
8. From a Command Prompt in the folder the console runs from, run
uft-migrate diagnostics triage "<the zip>" --check-secret and type the
ALM password at the prompt; repeat with the ALM user name and the ALM
server's host name. Do the same for the second zip.
9. PASS: nothing you type is shown; each time the report ends saying the value
appears nowhere in the bundle, and the exit code is 0.
10. Run uft-migrate diagnostics collect --no-run --list.
11. PASS: it prints what it would collect and writes no new bundle under
out\_support\.
12. Optional — a conversion you stop. Cancel a conversion as in TC-11a step 4,
on a disposable project, and read that step's warnings first: Cancel is a
hard stop that rolls nothing back.
13. PASS: its Conversion Failed dialog asks nothing; its last line reads To
send details to Merito support, use Collect Diagnostics (bottom left).
Nothing is sent automatically.
L. Free edition and licensing¶
Both cases need a folder of more than 100 test cases, and TC-30 needs a
license file from Merito whose limit is above 101, or that has no limit, and
that has not expired. Build the folder from one small UFT GUI test with no
cross-test calls — here C:\UFT\Smoke — as 101 copies, each in a numbered
folder of its own, so that every copy keeps the test's own name (a renamed
test folder no longer matches its .usr; see
advanced_troubleshooting.md §1d). In
PowerShell:
1..101 | ForEach-Object {
$dir = "C:\Phoenix\Limit101\{0:D3}" -f $_
New-Item -ItemType Directory $dir | Out-Null
Copy-Item -Recurse C:\UFT\Smoke $dir
}
TC-29 — Over the limit: the analysis runs, conversion is refused
1. Run uft-migrate license. PASS: it names the free edition, Free edition
· up to 100 tests. If a license is installed, remove it for this case —
uft-migrate license remove <license id>, with --all-users from a
Command Prompt opened with Run as administrator for one installed for
every user — and install it again afterwards.
2. Step 2: UFT FileSystem. Step 3: Source Roots = C:\Phoenix\Limit101.
Step 5: Run Analysis.
3. PASS: the analysis completes, and the card shows the verdict the test
earns on its own (GO for a clean test), its line reading Scoping
required: 101 test cases, over the free edition limit of 100. The status
line ends with the over-limit notice, which begins This conversion
includes 101 test cases, by Merito Phoenix for UFT's count. and names Merito's
consultation request form.
The step header card reads 101 test cases, over the free edition limit of
100., and its button Scope this conversion with Merito opens the
consultation request form in the browser. Scan HTML names the edition,
Free edition · up to 100 tests, and carries the Scoping required
notice; scan_report.json holds licensing with test_cases 101,
limit 100, edition free and within_limit false.
4. Press Open Scoping Summary. PASS: scoping_summary.html opens from
the run folder, with Test Cases 101 and License Limit 100. Search it,
and scoping_summary.json, for Smoke and for Limit101: neither the
test's name, nor its folder, nor any line of its script is in them.
5. Out-of-scope tests = 101; Run Analysis again. PASS: the count is
still 101 — parking does not lower it — and the scoping summary shows 1
test Parked for a later wave.
6. Press Next. PASS: Scoping Required, giving the notice and How test
cases are counted:; the wizard stays on Step 5.
7. From a Command Prompt in your profile folder:
uft-migrate run --source-root C:\Phoenix\Limit101 --run-id LIMIT101.
PASS: exit code 2. The JSON on stdout has "status": "license-limit",
licensing.test_cases 101 and no go_no_go. Its message, also on
stderr, begins Conversion refused. No test was converted, backed up or
changed. and, because out\LIMIT101 holds no analysis, ends Run uft-migrate scan
with the same source folders to write the scoping summary.
No file was written under out\LIMIT101, and UFT did not start.
8. Delete C:\Phoenix\Limit101\101, leaving 100, and run the same command
with --run-id LIMIT100. PASS: it is not refused: stderr shows license:
100 test case(s) counted under the source folders; Free edition · up to
100 tests, and the conversion starts. Let it finish, or press Ctrl+C once
the first test has converted and close UFT.
9. Optional — ALM, on a project of more than 100 test cases that you may
analyze but must not convert. Nothing this step runs writes to ALM,
whatever its outcome. Run a Deep analysis. PASS: migration_log.txt
holds an alm-aom-progress line reading [analysis] deep: with the count
and Each build is deleted once it is checked and measured.; the report
carries the Technical Conversion Breakdown, and its depth note ends
Builds were deleted after they were checked and measured, because this
project was over its test-case limit.; no alm_aom_work\test_<id>_build\
folder is left in the run folder. Stop here unless the run folder's
scan_report.json holds licensing with within_limit false and
test_cases over 100, and uft-migrate license names the free edition.
Then, with the connection flags and UFT_MIGRATE_ALM_PASSWORD set, run
the upload rehearsal, which never writes to ALM:
uft-migrate convert --alm --upload --dry-run --run-id <that run id>.
PASS: exit code 2 and "status": "license-limit"; the run folder's
scan_report.html and resume_state.json are unchanged.
10. Optional — the real upload's refusal, only on a disposable pilot project
seeded with copies of more than 100 test cases, which you can restore
from its backup. Never run it on a project you must not convert: if the
limit let the upload through, it would convert every test in place.
Analyze the pilot project, and stop unless its scan_report.json and
uft-migrate license read as in step 9. Then, with the connection flags
and UFT_MIGRATE_ALM_PASSWORD set: uft-migrate run --alm --upload
--confirm-alm-backup --run-id <its analysis's run id>. PASS: exit code
2, "status": "license-limit" and "alm_status": "license-limit"; the
tests' Modified dates in ALM are unchanged; the run folder's
scan_report.html and resume_state.json are unchanged, and it has no
new executive_summary.* and no alm_wave_stop.json; the crash
supervisor that ran the upload closed the wave it opened, and
resume\alm_wave.json gives it the status closed-no-writes.
TC-30 — A license lifts the limit
Re-create C:\Phoenix\Limit101\101 (copy C:\UFT\Smoke into it again), and
keep the Migration Console open on Step 5 with TC-29's analysis.
1. Copy the license file, and in the copy change one letter of the
licensee's name. From a Command Prompt opened with Run as
administrator: uft-migrate license install "<the changed copy>"
--all-users. PASS: exit code 2 and License not installed: … was
changed after Merito issued it, or Merito did not issue it. Merito Phoenix for UFT
ignores it.; <install folder>\licenses\ is unchanged, and
uft-migrate license still names the free edition.
2. From the same prompt: uft-migrate license install "<the license file>"
--all-users. PASS: exit code 0; it prints Installed license, the
license id and the licensee, for all users of this PC., and Edition:
Licensed to the licensee and the limit; <install folder>\licenses\
holds <license id>.license.json.
3. uft-migrate doctor. PASS: the license row is [ OK ] and names the
license: its id, its expiry and the ALM projects it covers.
4. In the Migration Console, without running the analysis again, press
Next. PASS: Step 6 opens; the version line's second line reads
Licensed to and the licensee; the step header card reads Need Merito
Professional Services to lead the migration? again. (If you closed the
console since TC-29, reopen it and run the analysis once: it then reports
no over-limit notice.)
5. Back on Step 5, clear Out-of-scope tests and press Run Analysis.
PASS: no Scoping required; Scan HTML names the license as the edition;
scan_report.json's licensing holds test_cases 101, edition
licensed and within_limit true. Next opens Step 6, and Run
Conversion starts converting (let it finish, or cancel after the first
test and close UFT).
6. Optional — an expired license file: uft-migrate license install "<the
expired file>". PASS: exit code 2, License not installed: license …
expired on … Ask Merito for a renewed license., and nothing is
installed.
7. Optional — silent deployment, from an administrator Command Prompt on a
machine without Phoenix; read each exit code with echo %ERRORLEVEL%:
start /wait MeritoPhoenixForUFT-<version>-Setup.exe /VERYSILENT
/SUPPRESSMSGBOXES /NORESTART /ACCEPTEULA /LICENSEFILE="<full path>"
/LOG="C:\Windows\Temp\phoenix-install.log". PASS: exit code 0; the log
has license: lines, the last reading installed for all users from and
the path; uft-migrate license names the licensee.
8. Optional — the same command with /LICENSEFILE= naming a file that is
not there. PASS: exit code 2: Setup stopped before it installed anything.
9. Optional — the same command with an expired license file. PASS: exit
code 10, and Phoenix is installed; the log's license: lines say why the
file was not installed, then If a license was installed earlier, it still
applies. If not, the free edition is active.
10. Optional — run the installer again over the installation, as an upgrade.
PASS: <install folder>\licenses\ still holds the license, and
uft-migrate license names it.
11. Clean up: to return the machine to the free edition, run
uft-migrate license remove <license id> --all-users from an
administrator prompt. PASS: exit code 0 and Edition: Free edition · up
to 100 tests. (Uninstalling Phoenix would have left
<install folder>\licenses\ and the license in it: licenses survive an
uninstall.)
Suggested sign-off matrix¶
| Area | Cases | Sign-off |
|---|---|---|
| Environment | TC-01–02 | |
| Console basics | TC-03–04 | |
| Analysis | TC-05–06 | |
| Safety rails | TC-07–10, TC-10a, TC-10b | |
| Conversion | TC-11, TC-11a, TC-12–13 | |
| Execution | TC-14 (CLI-only, optional), TC-14a, TC-15 | |
| Power features | TC-16–19 | |
| Reporting | TC-20 | |
| Version control & locks | TC-21–22 | |
| Crash recovery (validation runs only) | TC-23–27 | |
| Diagnostics | TC-28 | |
| Free edition and licensing | TC-29–30 |