Connect to, launch or stop the 1C test client.

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. Actions:

• connect(port=null, host='127.0.0.1', version=null, profile=null) Connect to a running /TESTCLIENT -TPort client using port or a list_profiles profile; explicit parameters override the profile. version must match the full running version (omitted: built-in default). Connect before UI actions. A new host/port creates a connection; the same host/port reconnects that client: connection_id is retained, but find elements again.

• disconnect(force=False) Close the connection to the test client. force=true interrupts a pending network call; its result may be unknown. The 1C application remains running.

• get_logging_status() Return call logging status, paths, call count, disk usage and any reason recording stopped.

• launch_client(base=null, port=null, server=False, user=null, password=null, version=null, exe=null, extra_args=null, wait=120, connect=True, desktop='default', profile=null) Launch and optionally connect. base is a file infobase path, or 'server\infobase' with server=true; alternatively use a list_profiles profile. Explicit parameters override the profile. user/password are infobase credentials; the password is visible in the process command line. exe is the full path to 1cv8/1cv8c (with .exe on Windows); omitted: configured or auto-detected installation. A version prefix selects the latest matching build; use a full version or exe for an exact build. Omitted port allocates a free local port; each launch creates a connection_id. wait covers total startup including readiness; increase for slow bases. Linux default needs DISPLAY/XAUTHORITY; isolated needs Xvfb. isolated uses a separate desktop (Windows 10+/Linux) and stops with the server. connect=false confirms only an answering port, not a usable client.

• list_connections() List registered clients with connection_id, profile, host, port, base, user and recording status. busy, active_action and active_seconds describe the running call. connected reports an open connection, not client responsiveness. base/user are known for clients launched here.

• list_profiles() List named launch/connect profiles and their descriptions and settings, without passwords. Pass the name as profile to the listed action. Does not connect to or launch a client.

• start_logging(screenshot_mode=null, reports=null) Start a call journal. Repeated start keeps the current journal. screenshot_mode: off, actions (changes and errors), or all calls; default follows server settings. reports: ["html"], ["allure"], ["html", "allure"], or ["none"] for JSONL only. Omit reports to use the server's configured formats; the response lists the selected reports. Saves files on the server. Allure results are finalized when logging stops.

• stop_client(graceful_timeout=15) Stop the test client started by launch_client in this connection, and disconnect from it. Tries normal exit for graceful_timeout seconds (0..120, default 15), confirming known exit questions, then forces termination if needed. 0 forces termination immediately. Unsaved changes may be lost. Returns shutdown: graceful, forced, or already_exited; forced includes shutdown_reason. A failed stop retains process ownership for retry.

• stop_logging() Stop call logging, finalize selected reports and return their paths. Does not stop the client. Set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details.

Application-level state: active window, child objects, errors, dialogs, limits. Also available: tc_field(action="is_visible"), tc_field(action="is_enabled"), tc_field(action="get_context_menu").

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. Actions:

• clear_file_dialog_result() Clear a previously set file-dialog result. (1C 8.3.25+)

• get_active_window() Read the active window: ref/class/title/platform_version, optional form_name/url/home_page/is_main. title is the form caption (null: no form or unreadable); url is empty without a link. form_name is a metadata name, not the form's GUID name; it is only attempted when the window supplies no caption and may remain absent; absence says nothing about the form. Read it explicitly with tc_app(action="get_child_objects") on the window ref. platform_version identifies this connection; unsupported actions report available_since. addressable=false means no element address, not a window type. native=true with recovery=close_window indicates a local preview to close before addressing form elements. active_window_unavailable gives recovery guidance; no_active_work_window requires opening a form with tc_window(action="execute_command"). (1C 8.3.3+)

• get_child_objects(ref=null, scope='window') Read one level: parent and children: [...], with class/title and optional name/type/form_name. type is the platform element kind (null if unknown); ManagedForm.form_name is its metadata name. Omitted parent uses the last observed active window, querying it if none was observed. scope=application without a parent lists application windows. Windows/command buttons may include url; windows may include home_page/is_main. Address the parent with ref; children contain ref values. For a whole subtree, pass root_ref to tc_find(action="find_objects"). (1C 8.3.3+)

• get_current_error() Get info about the session's last CLIENT error (none → null). error is the main description; details preserves additional text, including nested causes, module locations and stacks. Application messages (e.g. unfilled fields or posting refusal) are read with tc_window(action="get_user_message_texts"); they may include earlier actions. (1C 8.3.3+)

• get_max_action_time() Get the max action-execution time in seconds (set via tc_app(action="set_max_action_time"); None if unset).

• get_parent(ref*) Get an element's parent in parent: [...]. The server resolves the parent's own address and returns it with the available object metadata. Address the element with ref; objects in parent contain their own ref values. (1C 8.3.24+)

• get_performance(clear=False) Get accumulated session performance counters (calls, duration, sent, received). Set clear to also reset them, so the next read measures only what happened after this call. (1C 8.3.6+)

• get_screenshot(scale=100, grid=False, region=null) Capture the connected 1C window with popups as an image, without changing focus. Requires a local client on Windows or Linux with X11/XWayland and desktop access. scale: 25..100 percent. Optional region=[x,y,width,height] uses original screenshot pixels; grid labels those coordinates. capture_complete=false means some popups are missing. Screenshots are not recorded in scenarios.

• set_file_dialog_result(result=True, filename=null, filter_index=0) Predefine the NEXT file dialog: result=true with filename (or a list for multiple files) selects; false cancels. filter_index is 0-based. Call BEFORE opening; cannot answer an open dialog. Each answer is consumed once. On 8.3.25+, replaces pending answers; clear_file_dialog_result clears unused ones. Older platforms cannot clear them: prepare only the next dialog. (1C 8.3.8+)

• set_max_action_time(seconds*) Set the max action-execution time in seconds: how long a result-returning action may take before the call gives up (0 = wait indefinitely). Stored on the client (no network call) and applied to every subsequent command. ref selects the client; otherwise set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details. Use returned references unchanged in ref; re-find expired elements.

Actions on the client application window. Also available: tc_field(action="is_visible"), tc_field(action="is_enabled"), tc_field(action="get_context_menu"), tc_app(action="get_parent").

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. Actions:

• activate_window() Activate the current active window. (1C 8.3.3+)

• answer_dialog(confirm=True, timeout=5) Wait up to timeout seconds and answer a modal question: confirm=true presses Button0, false Button1. Never presses Button2; inspect the question/window for other choices. Returns answered='Да'/'Нет' and question; both null means no dialog, question alone null means unreadable text. (1C 8.3.3+)

• choose_user_message(text*) Click the first user message matching text in the active window; * and ? are wildcards. Use get_user_message_texts to read the available messages first. (1C 8.3.3+)

• close_user_messages_panel() Close the window's user-messages panel. This is also how you tell which messages belong to which action: clear the panel, perform the action, then read the messages. (1C 8.3.6+)

• close_window(ref=null) Close the window at ref, or the active window if omitted. Returns closed only after verifying that the window disappeared. If it remains open, returns window_not_closed and target; inspect the form or answer its dialog before retrying. Also closes an active local print preview when ref is omitted. (1C 8.3.3+)

• execute_command(command*) Open a navigation link, e.g. 'e1cib/list/Справочник.Контрагенты', 'e1cib/app/Обработка.Имя' or a URL returned by the command interface. For a button name or title, find it and use click. Returns the resulting window; window_changed=false reuses the previous window description. An opened error window is a failure. (1C 8.3.3+)

• get_command_interface() Get the window's command interface → collection of buttons/groups. (1C 8.3.3+)

• get_user_message_texts() Get the user-message texts currently shown in the window → list of strings. They may include earlier actions; the application can also replace the list with identical messages. To judge one action, call tc_window(action="close_user_messages_panel") first, then the action, then this. Messages may appear after the action returns. (1C 8.3.3+)

• goto_next_window() Go to the next open window from the active main application window. The client returns an error if navigation is unavailable. (1C 8.3.6+)

• goto_previous_window() Go to the previous open window from the active main application window. The client returns an error if navigation is unavailable. (1C 8.3.6+)

• goto_start_page() Go to the start page from the active main application window. The client returns an error if navigation is unavailable. (1C 8.3.6+) ref selects the client; otherwise set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details. Use returned references unchanged in ref; re-find expired elements.

Actions on a form field, button, group or element addition. Choose action. Also available: tc_app(action="get_parent").

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. ok=true means accepted; verify effects by reading state. target_check: present, unknown (uncheckable), off (disabled); present does not prove an effect. target_hidden=true means the target exists but is invisible; it describes the element, not its ancestors. Its absence says nothing; hidden targets may still act (e.g. activate). Invalid addresses are rejected only where the address can be checked; an unverified empty read may mean a missing target. failure_context describes state/editor/choices; its complete=false means incomplete diagnostics. Actions:

• activate(ref*) Focus an element, switch a page or make a table column current; click does not do this. Commits pending input_text only by focusing a DIFFERENT focusable element; tc_form(action="goto_next_element") lets the form choose. Reports page visibility; still hidden returns target_hidden. No changed flag: verify via get_text/get_current_page, tc_form(action="get_current_element") or tc_table(action="get_current_item").

• cancel_edit(ref*) Cancel editing an input field. (1C 8.3.6+)

• choose_from_drop_list(ref*, value*) Pick a value from a field's open drop-down list by its display text (e.g. a colour name) or by its 0-based index in the list. The value is written at once — no focus change is needed. changed may come back null here even when the value did change: with the list open the value cannot be read. A changed window is returned when readback is enabled; inspect it before continuing. window_changed=false reuses the previous window description. Read the field with tc_field(action="get_text") to confirm. (1C 8.3.6+)

• clear(ref*) Clear an input field's value.

• click(ref*, diagnostics=False, diagnostics_wait=2.0) Click a button, field, group, decoration or command-interface button. Use activate to focus inputs/cells/pages. window, when present, is the active window afterwards. window_changed=false means the previous window description still applies. diagnostics=true also reads messages, possibly from earlier actions. diagnostics_wait=0..60 seconds polls while messages are unavailable/empty; 0 reads once. Individual requests use set_max_action_time. diagnostics.status is read/unavailable/failed; null messages are not an empty list. ok or absent messages do not prove business success.

• click_view_status_item(ref*, index*) Click a view-status item by 0-based index (or by its text). Nothing here proves the item was there: the platform answers the same when the form has no view-status line at all, and reading the texts first does not settle it either — that read comes back empty even while a search or filter is active. Judge by the list itself: read the rows before and after. (1C 8.3.16+)

• close_drop_list(ref*) Close a field's drop-down list. Verify with tc_field(action="drop_list_is_open"). (1C 8.3.6+)

• create(ref*) Create a new object from a reference field: opens the new object's form, as the field's '+' does. The field must have the FOCUS first — call tc_field(action="activate") on it, otherwise the command is accepted and nothing opens. Verify by reading the active window. (1C 8.3.6+)

• current_check(ref*) Whether a form BUTTON is pressed, or shows a check mark next to it. Only buttons answer meaningfully: anything else — a checkbox field, a page, a table — always reports false, which means 'not applicable', not 'switched off'. Read a checkbox with tc_field(action="get_text") ('Да'/'Нет') and the active page with tc_field(action="get_current_page"). (1C 8.3.16+)

• current_mode_is_edit(ref*) Whether a table row or spreadsheet-document field is currently in edit mode. (1C 8.3.3+)

• current_opened(ref*) Whether a form group is currently open. (1C 8.3.16+)

• decrease_value(ref*) Decrement a numeric (spinner) field. A track bar does NOT take this — move it with tc_field(action="goto_value") in percent. When the value does not move, applicable: false in the answer means the method does not fit this kind of field.

• delete_view_status_item(ref*, index*) Delete a view-status item by 0-based index (or by its text) — this is how a filter or a search chip is dropped. Nothing here proves the item was there: the platform answers the same when the form has no view-status line, and reading the texts first does not settle it either. Judge by the list itself: read the rows before and after. (1C 8.3.16+)

• drop_list_is_open(ref*) Whether a field's drop-down list is open. (1C 8.3.6+)

• execute_choice_from_choice_list(ref*, value*) Pick from a field's choice list by its display text or by its 0-based index. Reports changed/value_before/value_after — the field's value read before and after, same as tc_field(action="choose_from_drop_list"). A changed window is returned with readback enabled. window_changed=false reuses the previous window description.

• get_choice_list(ref*) Read radio-button options, an input's open drop-down list or a form's open choice list. For an input, open its list immediately before reading: the answer describes whichever drop-down is currently open. items contains {presentation, text}; presentations contains the displayed texts to select. A closed input list may return items=[] with status=unknown. (1C 8.3.12+)

• get_command_bar(ref*) Get an element's own command panel object, if it has one. This is NOT the list of buttons: the panel is a container, and its buttons are read with a separate tc_app(action="get_child_objects") on the returned ref. An empty result means the element has no command panel of its own — a list table is the usual case, its buttons live in a form group next to it. (1C 8.3.3+)

• get_context_menu(ref*) Get an element's context menu. The platform returns the menu as a form GROUP, not as a list of commands: 'menu' holds that group, and its items are read with a separate tc_app(action="get_child_objects") on the group's ref. (1C 8.3.3+)

• get_current_page(ref*) Get the current page of a page group. To switch pages use tc_field(action="activate"): a click on a page does not switch to it. tc_field(action="current_check") is useless here — pages always report checked=false. (1C 8.3.6+)

• get_data_presentation(ref*) Get an element's data presentation. Form fields only — not form decorations, and on a table the answer is always null. An empty input or label field returns "". presentation is null when no value was available; that is not proof that the field has no presentation.

• get_edit_text(ref*) Read an input field's edit buffer — what is being typed, which is not necessarily what the form holds. get_data_presentation reads the accepted value; get_text reads displayed text. An empty input buffer returns ""; null means unavailable. (1C 8.3.3+)

• get_linked_window(ref*) Get the linked window of a command-interface button. An empty answer means the button has no linked window — but only when target_check says the button itself is there; a wrong ref answers empty too, and the check is what tells the two apart. (1C 8.3.6+)

• get_state_presentation(ref*) Read a form field's state presentation. An unavailable value is explained in the answer; null does not confirm that the field has no state presentation. (1C 8.3.16+)

• get_text(ref*) Read displayed text (checkbox text follows the client language). An empty input or label field returns "". For an edit buffer use get_edit_text. If text is unavailable, the answer explains the limitation and suggests another reading action where applicable. null does not confirm an empty field. (1C 8.3.12+)

• get_tooltip(ref*) Read an element's tooltip text (empty → None). (1C 8.3.3+)

• get_view_status_item_texts(ref*) Get the view-status item texts of a form-element addition → list of strings. Do not use it to tell whether a filter or search is active: with a list narrowed down to one row by search the platform still answers with an empty collection. Check the effect by reading the rows. (1C 8.3.16+)

• goto_value(ref*, percent*) Move a TRACK BAR to a value in PERCENT (0..100). This is a track bar method: on any other kind of field the command is accepted and nothing moves, and the answer then carries applicable: false. A spinner is stepped with increase_value/decrease_value instead. Returns changed/value_before/value_after. (1C 8.3.6+)

• increase_value(ref*) Increment a numeric (spinner) field. A track bar does NOT take this — move it with tc_field(action="goto_value") in percent. When the value does not move, applicable: false in the answer means the method does not fit this kind of field.

• input_text(ref*, text*, finish=True) Enter text; text="" clears. finish=true moves the owning form's focus once and verifies ordinary input; false keeps the edit buffer (e.g. for reference choice/cancel). Reference input may still require selection. Changed pending text causes pending_input_changed: re-enter or cancel. committed=true/false/null means accepted/pending/unverified; edit_finished means focus left; changed compares displayed text. Numeric formatting may yield verification=numeric_equivalent and committed=null. These flags do not confirm saving. For table cells use tc_table(action="set_cell_text"); finish text documents with activate on another element, spreadsheet cells with tc_doc end_edit_current_area.

• is_enabled(ref*) Read the element's availability. A command can still refuse execution in the current form state. (1C 8.3.3+)

• is_readonly(ref*) Whether an element is currently read-only — that is the element's own read-only property. Two other things look the same and are NOT this: an element switched off entirely (read that with tc_field(action="is_enabled")), and a spreadsheet-document field shown in view mode, which neither read reflects — there, tc_doc(action="begin_edit_current_area") runs the cell's details instead of editing. (1C 8.3.3+)

• is_visible(ref*) Whether an element is currently visible. Returns an error instead of visible=false when there is no object at ref: for this read the protocol does report a missing target, so a mistyped address cannot pass for a hidden element. On the pages of a page group this does NOT tell you which page is on screen — several pages report visible=true at once; use tc_field(action="get_current_page") for that. (1C 8.3.3+)

• open_drop_list(ref*) Open the drop-down list of a reference/enum field (call before choose_from_drop_list). (1C 8.3.6+)

• open_field(ref*) Open a reference field's value (F4 / follow the link).

• read_fields(targets*, properties=null) Read 1–100 fields of the active form without moving focus. properties defaults to ['text']; presentation reads data, edit_text reads the editing buffer. visible/enabled/readonly are optional. Table-column text reads the current row. Results follow input order (index is 0-based); unavailable properties remain null with a reason. Reads are sequential, not an atomic snapshot. targets is an array of {ref} objects returned by discovery. (1C 8.3.12+)

• select_option(ref*, value*) Pick a radio-button option by its display text or by its 0-based index.

• select_value(ref*, value=null, match=null, choice_table=null, choice_column=null, data_type=null, expected=null, max_rows=500, timeout=180) Select exact value text (drop-down first) or match={column title: exact text} in a choice form. Ambiguous/incomplete searches refuse selection. choice_table is an exact table name; choice_column limits value to a column title; data_type chooses a displayed type in the standard type dialog. expected checks accepted field text. Returns accepted value and verification. max_rows=1..10000; timeout is in seconds, 0<timeout<=3600, and covers the action. Failure leaves the UI and does not undo sent choices. Table cells use the current row and leave row editing open. (1C 8.3.12+)

• set_check(ref*) Toggle a checkbox field. Inside a table this acts on the column that is the CURRENT cell, so make the target column current first — tc_field(action="activate") on the column element does that; a click on the cell does not.

• set_fields(entries*) Fill 1..100 input fields or checkboxes in one active form, in order. Each entry has exactly one of text, checked (boolean), or select={value: exact text} / select={match: {column title: exact text}}; select accepts tc_field(action="select_value") options. Empty text clears; matching checkboxes are not toggled, unknown states stop (Russian/English Yes/No supported). Stops on refusal, pending choice, window change or unconfirmed value; earlier changes remain. Rechecks all values at the end; final_verified=null may mean equivalent numeric formatting. Results use 0-based input indexes. Does not save the document. entries contains {ref, text}, {ref, checked}, or {ref, select} objects; use discovered references unchanged. (1C 8.3.12+)

• start_choosing(ref*) Open a reference field's choice form. Handles focus and table-cell editing. For CalendarField, selects the current date like a double-click; use goto_date first. Returns opened and the active window. A calendar selection need not open another window.

• start_choosing_from_choice_list(ref*) Start choosing from a field's choice list.

• title_is_shown(ref*) Whether an element's title is shown. (1C 8.3.25+)

• wait_for_drop_list_generation(ref*, timeout=60) Wait timeout seconds (integer 0..65535) for a generated drop-down; returns generated. The result is not tied to ref and may be true before this field's list opens. Open this field's list first, then read it immediately. (1C 8.3.4+) ref selects the client; otherwise set connection_id when several clients are connected. targets/entries references also select it; all must belong to one connection. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details. Use returned references unchanged in ref; re-find expired elements.

Actions on document fields and spreadsheet areas. Choose action. Also available: tc_field(action="is_visible"), tc_field(action="is_enabled"), tc_field(action="get_context_menu"), tc_app(action="get_parent").

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. ok=true means accepted; verify effects by reading state. target_check: present, unknown (uncheckable), off (disabled); present does not prove an effect. target_hidden=true means the target exists but is invisible; it describes the element, not its ancestors. Its absence says nothing; hidden targets may still act (e.g. activate). Invalid addresses are rejected only where the address can be checked; an unverified empty read may mean a missing target. failure_context describes state/editor/choices; its complete=false means incomplete diagnostics. Actions:

• begin_edit_current_area(ref*) Start editing the current spreadsheet area; follow with input_text and end_edit_current_area. In view mode this can instead open a drill-down menu, object or field chooser. A menu may leave the active window unchanged; use execute_choice_from_menu to continue.

• click_formatted_doc_hyperlink(ref*, index*) Click a hyperlink in a formatted-document field by 0-based index (or by its text). On a document without links the platform answers the same and puts up its own error window, and tc_doc(action="get_formatted_string_hyperlinks") cannot be used to check first: for a formatted DOCUMENT it answers with an empty list even when the document does have a link (it lists links only for a formatted-string label). Judge by what the click was supposed to do. (1C 8.3.25+)

• click_formatted_string_hyperlink(ref*, index*) Click a hyperlink in a formatted string by 0-based index (or by its text). ref may be a label field or a form decoration bearing the formatted string. (1C 8.3.13+)

• click_html_hyperlink(ref*, index*) Click an HTML link. The platform may open the FIRST link regardless of an in-range index; out-of-range indexes fail. text has no effect. Verify the resulting navigation. (1C 8.3.25+)

• end_edit_current_area(ref*, cancel=False) Finish editing the current spreadsheet-document area. Set cancel to discard the edit instead of committing it. Returns the cell address and its text before/after finishing; changed compares those values, including when an edit is cancelled.

• find_text(ref*, text*, match='contains', case_sensitive=False, area=null, start_address=null, max_cells=1000) Find literal spreadsheet text (match=contains/exact, case-insensitive by default); return cell addresses/text without moving the current area. area restricts a cell/rectangle (8.3.25+). max_cells=1..10000 limits scanned positions, not matches. If complete=false, resume with start_address=next_address and unchanged text/match/case_sensitive/area. Empty matches proves absence only in the successfully scanned part. (1C 8.3.13+)

• get_area_text(ref*, area=null) Get the text of ONE spreadsheet-document area; omit area to read the current one. tc_doc(action="get_current_area_text") is the older form of this same call and answers identically; prefer this one. (1C 8.3.6+)

• get_current_area_address(ref*) Get the address of the current spreadsheet-document area.

• get_current_area_field(ref*) Get the field of the current spreadsheet-document area. (1C 8.3.2+)

• get_current_area_text(ref*, area=null) Get the text of ONE spreadsheet-document area; omit area to read the current one. This is the older form of tc_doc(action="get_area_text"), which the platform deprecated in 8.3.6 in favour of that one; prefer get_area_text.

• get_doc_area_horizontal_size(ref*) Get the horizontal size (max column number holding data) of a spreadsheet-document. (1C 8.3.13+)

• get_doc_area_vertical_size(ref*) Get the vertical size (max row number holding data) of a spreadsheet-document. (1C 8.3.13+)

• get_formatted_string_hyperlinks(ref*) Get a formatted string's hyperlink presentations. (1C 8.3.25+)

• get_html(ref*) Read the HTML of a formatted/HTML-document field. After the form has put up a menu or a modal choice list, the platform stops returning this field's content until it is written again — an empty answer right after such a window does not mean the field is empty. (1C 8.3.8+)

• included_in_merged_area(ref*, address*) Return the address of the merged area containing the cell (e.g. 'R1C1'), or None if the cell is not part of a merged area. A null answer is ambiguous in one more way: it also comes back when the document has no such cell or no area by that name — the platform does not distinguish the two, and neither can this action. Only the FORM of the address is checked here (cell, range, area name, intersection); whether it exists is up to the document. (1C 8.3.25+)

• input_html(ref*, html*, attachments=null) Set HTML/text into a formatted-document field. attachments maps an image name used in the HTML (e.g. -> "p1") to that image as a base64 string; src must exactly match the attachment name. Names must be identifiers (no dots). (1C 8.3.8+)

• read_document(ref*, start_address=null, max_cells=1000, area=null) Read nonempty spreadsheet cells as rows with cell addresses and merged-cell spans. Optional area is a rectangle such as R2C3:R8C5 (platform 8.3.25+), clipped to the document's data bounds. Intersecting merged cells retain their full address/span, even if they start outside area. If complete=false, pass next_address as start_address with the same area to continue. max_cells limits positions scanned per call (1–10000). Does not move the current area.

• set_area_text(ref*, address*, text*) Set a spreadsheet cell's text by address, e.g. R2C1. Selects the cell, starts and finishes editing, then reads the result. Empty text clears it. Returns verified, changed and value_before/value_after. Numeric formatting can return verified=null with verification=numeric_equivalent. Rounded output returns value_verification_inconclusive: editing finished, but the exact value is not verified. Requires an editable document.

• set_current_area(ref*, address*) Set the current area of a spreadsheet-document field (e.g. 'R1C1').

• text_within_area_bounds(ref*, area=null) Whether the text in a spreadsheet-document area fits within its bounds (True) or is clipped to '#####' (False). Pass area (e.g. 'R1C1'); omit to check the current cell. (1C 8.3.25+)

• write_content_to_file(ref*, filename=null, file_format=null, filter_index=null, save_as=null) Save HTML/formatted/spreadsheet/text fields (not PDF fields). filename forces Save As, replacing and finally clearing pending dialog answers on 8.3.25+; older versions cannot clear unused answers, so prepare only the next dialog. Spreadsheet file_format: mxl/html/pdf/xls/xlsx/ods/docx; extension alone does not select it. Alternatively use 0-based filter_index; mutually exclusive with file_format, omitted: first type. Without filename, use current name unless save_as=true; predefine possible dialogs before EACH call with tc_app(action="set_file_dialog_result"). ok confirms accepted requests, not completed disk writing. Final cleanup failure separately returns cleanup_error and dialog_answer_cleared=false; the next filename call retries cleanup before saving. (1C 8.3.8+) ref selects the client; otherwise set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details. Use returned references unchanged in ref; re-find expired elements.

Read and edit table or tree rows, manage selection and expand or collapse nodes. Choose action. Also available: tc_field(action="is_visible"), tc_field(action="is_enabled"), tc_field(action="get_context_menu"), tc_app(action="get_parent").

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. ok=true means accepted; verify effects by reading state. target_check: present, unknown (uncheckable), off (disabled); present does not prove an effect. target_hidden=true means the target exists but is invisible; it describes the element, not its ancestors. Its absence says nothing; hidden targets may still act (e.g. activate). Invalid addresses are rejected only where the address can be checked; an unverified empty read may mean a missing target. failure_context describes state/editor/choices; its complete=false means incomplete diagnostics. Actions:

• add_rows(ref*, rows*) Add and fill 1–100 rows: rows=[{cells:[{column: element name, text: ...}]}], at most 1000 cells. Each cell uses text for an input column or checked=true/false for a checkbox column, never both. Requires finished row editing. Stops at the first refusal; earlier edits remain. results use 0-based input indexes; added=null means creation could not be confirmed. Each completed row is checked when filled, not after later rows. Does not save the document. (1C 8.3.12+)

• can_be_expanded(ref*, row_column=null, row_value=null) Whether a table row/group can be expanded. Pass row_column+row_value to target a specific row by a column name or title; omit them to use the current row. can_expand=true does not promise that tc_table(action="expand") will work: rows reporting true have been observed to stay collapsed. The reliable evidence is tc_table(action="expand")'s own value_before/value_after pair.

• change_row(ref*) Start editing the current table row/column. Activate the intended column first. Needs an existing row not already in edit mode. edit_mode confirms whether editing started; null means it could not be checked. For text input use set_cell_text for automatic preparation.

• choose_row(ref*) Choose/double-click the current row: selects and closes a choice form, opens an item's card in a list (a folder's own card, not its contents). changed tracks ACTIVE WINDOW change only. If false, read the destination field: selection may have succeeded without closing a window.

• collapse(ref*, row_column=null, row_value=null) Collapse a form group or table node. For tables, row_column+row_value targets a row by column name/title; omitted: current row. No collapsible node is not an error. changed=false only for equal successfully read value_before/value_after; null for form groups, read failures or readback=off. can_be_expanded applies only to table rows and does not guarantee an effect; verify before/after.

• copy_row(ref*, confirm=null) Copy the current table row. On catalog/document lists a confirmation dialog may appear — set confirm=True/False to auto-answer it (default None: no dialog handling). (1C 8.3.25+)

• delete_row(ref*, confirm=null) Deprecated alias for delete_rows(scope="current"). Use delete_rows for new calls. (1C 8.3.3+)

• delete_rows(ref*, confirm=null, scope='current', unmark=False) Delete current or selected rows (selected: 8.3.6+, standard context-menu Delete/Mark, preserving selection). confirm=true/false answers; null leaves confirmation open. Lists may mark instead of remove. deleted=null means unverified. unmark=true removes marks (8.3.6+), only in lists with a standard marking command, not ordinary tables. (1C 8.3.3+)

• deselect_all_rows(ref*) Clear the table's row selection. Needs platform 8.5.1 or newer — on every earlier one the platform has no such method. Plain row navigation drops the selection down to the current row, which is the only way to undo a multi-row selection there. (1C 8.5.1+)

• deselect_row(ref*) Remove the current table row from the selection. Needs platform 8.5.1 or newer — on every earlier one the platform has no such method. The closest thing there is to pass over the row with toggle_selection set: that toggles it, so a selected row becomes unselected. (1C 8.5.1+)

• end_edit_row(ref*, cancel=False) Finish editing the current table row. Set cancel to discard the edits instead of committing them.

• expand(ref*, row_column=null, row_value=null, subordinates=False) Expand a form group or table node; subordinates also expands child rows. For tables, row_column+row_value targets a row by column name/title; omitted: current row. No expandable node is not an error. changed=false only for equal successfully read value_before/value_after; null for form groups, read failures or readback=off. can_be_expanded applies only to table rows and does not guarantee an effect; verify before/after.

• find_rows(ref*, conditions*, columns=null, case_sensitive=False, max_rows=500, max_matches=50, text_format='plain') Search selectable rows of the CURRENT table, respecting filters/collapsed groups; never a database-wide search. conditions is an AND-list of {column: displayed TITLE, text, match: exact/contains/starts_with/ends_with}; literal, case-insensitive by default. Ignore search highlighting for comparison; plain removes it in results, raw retains it. Empty text matches displayed emptiness. columns selects returned titles. max_rows bounds checked rows, not client response; max_matches bounds matches. complete covers this table; matches_truncated marks omitted matches. No stable order/row IDs. Uses read_rows: clears selection, may reposition an unavailable cursor on older platforms; refuses unfinished row edits. (1C 8.3.6+)

• get_cell_text(ref*, column*) Read the current row's displayed cell (may contain search markup). column is an element NAME or 0-based index; digit strings are indexes. Unknown/ambiguous names refuse; a matching title suggests the name. null does not prove emptiness. A COLUMN GROUP displayed as one column may return neighbouring/group text indistinguishable from the intended value; other-kind members may return null. A nonexistent table can also return text=null.

• get_current_item(ref*) Get the current item of a table → {ref}. ref: the table.

• get_current_row(ref*) Get the current table row as [{column: value}]. Returns [] if there is no current row or its values could not be read. Needs platform 8.5.1 or newer — on every earlier one, use get_selected_rows after moving to the desired row, or get_cell_text to read one column. (1C 8.5.1+)

• get_list_settings(ref*, max_rows=500, timeout=180) Read filters and sorting through the list's standard settings form. Closes settings opened by this call. filters contains expanded tree rows, including the root and groups; orders follows sort priority. Values are displayed text. max_rows limits each settings table (1–10000). timeout bounds the operation in seconds (greater than 0, at most 3600). (1C 8.3.12+)

• get_list_settings_fields(ref*, section='filters', max_rows=500, timeout=180) List available field captions for filters or orders through the standard list settings. Returns visible fields; collapsed branches are not traversed. Closes settings opened by this call. timeout limits the operation in seconds (0 < timeout <= 3600). (1C 8.3.12+)

• get_selected_rows(ref*) Read selected rows as {column title: displayed value} maps. Row order is not guaranteed. The platform chooses the columns. Missing columns are unread, not empty; empty text can also represent an omitted value. Values may contain search highlighting. Use read_rows to read all selectable rows of the current table. (1C 8.3.6+)

• go_one_level_down(ref*, row_column=null, row_value=null, column=null) Go one level down in a table tree. Pass row_column+row_value to target a specific row by a column value; row_column accepts a column name or title. Omit both to use the current row. Optional column names a column to read before and after the move; changed compares its cell text.

• go_one_level_up(ref*, row_column=null, row_value=null, column=null) Go one level up in a table tree. Pass row_column+row_value to target a specific row by a column value; row_column accepts a column name or title. Omit both to use the current row. Optional column names a column to read before and after the move; changed compares its cell text.

• goto_first_row(ref*, toggle_selection=False, column=null) Move to the first row of a table. Set toggle_selection to also toggle that row's selection. Pass column (the column element NAME) to have that cell read before and after the move: it comes back as value_before/value_after with changed=true when they differ. changed=false only means the two texts are the same — different rows can share a value; without column nothing is read and changed is null.

• goto_last_row(ref*, toggle_selection=False, column=null) Move to the last row of a table. Set toggle_selection to also toggle that row's selection. Pass column (the column element NAME) to have that cell read before and after the move: it comes back as value_before/value_after with changed=true when they differ. changed=false only means the two texts are the same — different rows can share a value; without column nothing is read and changed is null.

• goto_next_item(ref*) Move to the next item within a table. ref: the table.

• goto_next_row(ref*, toggle_selection=False, column=null) Move to the next row of a table. Set toggle_selection to also toggle that row's selection. Pass column (the column element NAME) to have that cell read before and after the move: it comes back as value_before/value_after with changed=true when they differ. changed=false only means the two texts are the same — different rows can share a value; without column nothing is read and changed is null.

• goto_previous_item(ref*) Move to the previous item within a table. ref: the table.

• goto_previous_row(ref*, toggle_selection=False, column=null) Move to the previous row of a table. Set toggle_selection to also toggle that row's selection. Pass column (the column element NAME) to have that cell read before and after the move: it comes back as value_before/value_after with changed=true when they differ. changed=false only means the two texts are the same — different rows can share a value; without column nothing is read and changed is null.

• goto_row(ref*, column=null, value=null, direction='down', toggle_selection=False, fields=null) Seek by column (displayed TITLE, not index) and value, or fields={title:value} for multiple columns; do not combine them. Values accept int/string and * ? wildcards; matching is case-sensitive displayed text. Searches FROM AND INCLUDING current row towards down/up, without wrapping. Step away first for the next match. A miss moves to the last row going down, or the first going up. toggle_selection toggles the destination; without criteria, the current row. found=null means no criteria or undetermined, never not-found. criteria uses titles; observed.column uses the element name. Refuses inactive containing pages. (1C 8.3.2+)

• is_expanded(ref*, row_column=null, row_value=null) Whether a table row is expanded. Without row_column this reads the CURRENT row. Pass row_column (column name or title) and row_value to read another row without moving the cursor.

• read_rows(ref*, max_rows=500, columns=null, text_format='plain') Read selectable rows within current filters/collapsed groups: row_count and at most max_rows (0: count only), unordered. columns selects returned titles; plain strips known search highlighting, raw retains it. Temporarily selects rows, then clears ALL previous selection. Keeps a usable current row; older platforms may move an unavailable cursor to first (cursor_repositioned=true). Single-selection tables are read sequentially (10000-row, 180-second scan limits), restoring the current row. Refuses unfinished row edits and inactive containing pages. (1C 8.3.6+)

• search(ref*, text*, max_rows=500, timeout=180, settle_time=2, columns=null, text_format='plain') Set the list's standard search string (empty clears), preserving filters. Returns rows after input readback and two equal row reads settle_time seconds apart; stability is not a platform completion signal. max_rows=1..10000; truncated means more rows. 0<settle_time<timeout<=3600; timeout covers the action. columns selects titles; raw retains search highlighting. Reading clears selection; unfinished edits refuse. (1C 8.3.12+)

• select_all_rows(ref*) Select all rows of a table. (1C 8.3.6+)

• select_row(ref*) Add the current table row to the selection. Needs platform 8.5.1 or newer — on every earlier one the platform has no such method. Build a selection there by moving through rows with toggle_selection set — each row the cursor passes is toggled. (1C 8.5.1+)

• set_cell_text(ref*, column*, text*) Set current-row column by element NAME; manages focus, continues existing row edits, finishes without discarding other cells, then reads back. Empty text clears. Returns verified/changed and displayed value_before/value_after; empty_value confirms emptiness despite formatting; numeric_equivalent may give verified=null. row_edit_pending means validation/reference choice kept editing: continue at the returned editor or end_edit_row(cancel=true). value_verification_inconclusive means editing finished but rounded output prevents exact verification.

• set_list_settings(ref*, filters=null, orders=null, replace=False, max_rows=500, timeout=180) Apply standard list filters/sorting; field is an exact available caption, value is displayed text. filters/orders follow their schemas. Adds by default; replace=true replaces only supplied sections ([] clears one). Success applies and closes settings; failure leaves them open and earlier edits may remain. 0<timeout<=3600 seconds covers the operation. (1C 8.3.12+)

• set_order(ref*, column*) Sort a table by a column, addressed by its TITLE. There is no direction parameter and no way to read the current direction: calling it again on the same column reverses the order. To learn which way it went, go to the first row and read a cell. (1C 8.3.6+)

• set_row_values(ref*, cells*) Fill 1..100 cells of the current row: {column: element NAME, text} or {column, checked}. Matching checkboxes are not toggled. Continues editing, finishes once after all entries, then reads back. Refusal/unexpected editor stops with earlier edits preserved for completion/cancel. completed counts entries; edit_finished confirms row completion; final_verified=null may mean numeric equivalence. Results use 0-based input order. Does not add rows, alter selection or save. (1C 8.3.12+)

• switch_row_delete_mark(ref*, confirm=True) Toggle the current row's deletion mark; confirm=true answers Yes, false No. dialog_answered proves only a response; changed is always null (no readable mark flag). To verify, invoke the mark command again and read its question: mark means currently unmarked, remove mark means marked. (1C 8.3.6+)

• table_add_row(ref*) Add a row to a form table. Fill its cells with set_cell_text using column element names. ref selects the client; otherwise set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details. Use returned references unchanged in ref; re-find expired elements.

Actions on a calendar field. Also available: tc_field(action="is_visible"), tc_field(action="is_enabled"), tc_field(action="get_context_menu"), tc_app(action="get_parent").

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. ok=true means accepted; verify effects by reading state. target_check: present, unknown (uncheckable), off (disabled); present does not prove an effect. target_hidden=true means the target exists but is invisible; it describes the element, not its ancestors. Its absence says nothing; hidden targets may still act (e.g. activate). Invalid addresses are rejected only where the address can be checked; an unverified empty read may mean a missing target. failure_context describes state/editor/choices; its complete=false means incomplete diagnostics. Actions:

• calendar_next_month(ref*) Move a calendar field to the next month. The command is accepted, but nothing readable about the field changes, so this cannot be verified. To move the date use tc_calendar(action="goto_date").

• calendar_next_year(ref*) Move a calendar field to the next year. The command is accepted, but nothing readable about the field changes, so this cannot be verified. To move the date use tc_calendar(action="goto_date").

• calendar_previous_month(ref*) Move a calendar field to the previous month. The command is accepted, but nothing readable about the field changes, so this cannot be verified. To move the date use tc_calendar(action="goto_date").

• calendar_previous_year(ref*) Move a calendar field to the previous year. The command is accepted, but nothing readable about the field changes, so this cannot be verified. To move the date use tc_calendar(action="goto_date").

• goto_date(ref*, year*, month*, day*) Go to a date (year, month, day) in a calendar field. Returns changed/value_before/value_after. ref selects the client; otherwise set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details. Use returned references unchanged in ref; re-find expired elements.

Actions on the managed form itself, including navigation between form elements and reading the focused element. Choose action. Also available: tc_field(action="is_visible"), tc_field(action="is_enabled"), tc_field(action="get_context_menu"), tc_app(action="get_parent").

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. ok=true means accepted; verify effects by reading state. target_check: present, unknown (uncheckable), off (disabled); present does not prove an effect. target_hidden=true means the target exists but is invisible; it describes the element, not its ancestors. Its absence says nothing; hidden targets may still act (e.g. activate). Invalid addresses are rejected only where the address can be checked; an unverified empty read may mean a missing target. failure_context describes state/editor/choices; its complete=false means incomplete diagnostics. Actions:

• compare_snapshot(snapshot_id*, ref=null) Compare the original form instance with its baseline; optional ref must identify the same instance. Returns changes/added/removed; observed means previously unread properties, not changes. complete/baseline_complete/errors mark read gaps. Uses baseline table settings; table_changes matches 1-based row positions and column titles, *_present distinguishes missing/empty cells. Tables are prepared before reading and stay selected; truncated tables are not compared. Added flags: '-' unread, 'unknown' failed. Stores no new snapshot; closed/reconnected forms need a new baseline. (1C 8.3.3+)

• create_snapshot(ref=null, include_tables=False, max_rows=500) Save ManagedForm state (default active) for later compare_snapshot; returns snapshot_id/summary. Reads visibility/availability/read-only and ordinary values; hidden branches skip further reads, disabled elements skip read-only. include_tables adds display-ordered rows up to max_rows each without expanding trees; requires active form/finished input (8.3.6+). Tables requiring sequential navigation report table_requires_sequential_read and complete=false; use read_rows separately. Rows stay selected; 8.3 may activate/establish current rows. Preparation precedes final reading. Excludes document contents; sequential, not atomic; may take seconds. (1C 8.3.3+)

• current_modified(ref*) Whether a form has been modified. (1C 8.3.3+)

• delete_snapshot(snapshot_id*) Delete a saved snapshot belonging to this connection.

• execute_choice_from_list(ref*, index*) Pick an item from a modal choice list by 0-based index or display text. Not a field's drop-down (use tc_field(action="choose_from_drop_list")). ref: the form (ManagedForm), not a field. (1C 8.3.8+)

• execute_choice_from_menu(ref*, index*) Choose an item from an open menu by 0-based index or display text. For a submenu, call again to choose its item. Address the form or the spreadsheet field that opened the menu. A spreadsheet field requires platform 8.3.25 or newer. (1C 8.3.8+)

• find_default_button(ref*) Find the form's default button. ref is the form's ref. (1C 8.3.3+)

• get_context(ref=null, save_as_snapshot=False, include_tables=False, max_rows=500, root_ref=null, visible_only=False, include_commands=True, result_mode='changes') Inspect ManagedForm elements (including hidden), state, values and input context; includes discovery, so no separate search is needed. Use tc_find(action="find_objects") alone for element lookup. May take seconds. result_mode=changes returns a full first read, then only new/changed elements and removed objects since the previous complete read of this form; changed=false means no changes. Other interaction fields describe the current state. full returns everything. result_mode and full_reason identify the actual response; context_id/compared_to identify automatic baselines. Filter changes or lost baselines return full. Incomplete reads return full and keep the prior baseline. save_as_snapshot creates a separate fixed snapshot for compare_snapshot without another read. include_tables adds up to max_rows per table without expanding trees; rows stay selected, 8.3 may activate rows. Excludes document contents. Flags: '-' unread, 'unknown' failed, null unavailable (not empty). form_details reports optional hints/type restrictions/choices availability. root_ref limits output to a subtree; include_commands=false omits buttons/command groups; visible_only excludes known hidden/inactive pages, retains unknown visibility. Output filters do not narrow reading or fixed snapshot scope. complete/errors mark read gaps; snapshot_error marks failed saving. Sequential reads. (1C 8.3.3+)

• get_current_element(ref*) Get the managed form's focused element as item: [{ref}]. ref: the form (ManagedForm). The platform can return no current element after navigating out of its fields.

• goto_next_element(ref*) Move focus to the next element in the managed form's tab order. ref: the form (ManagedForm). This can finish the current field's pending input; read the field's data presentation to verify acceptance. Reference fields may still require choosing a value.

• goto_previous_element(ref*) Move focus to the previous element in the managed form's tab order. ref: the form (ManagedForm). This can finish the current field's pending input; read the field's data presentation to verify acceptance.

• list_snapshots(ref=null) List saved snapshots for this connection, optionally restricted to one ManagedForm ref. Returns IDs, form titles, timestamps, element counts, sizes and global storage limits. Listing does not refresh last_used_at or verify forms are still open; a supplied ref is validated.

• wait_for_closing(window_title=null, timeout=60) Wait until a window closes, up to timeout seconds. Without window_title, watch the window active AT THE MOMENT OF THE CALL. After a close, pass window_title to check the closed window. Switching windows or opening a preview does not count as closing. If the target cannot be identified or its absence confirmed, return ok=False. (1C 8.3.3+) ref/root_ref selects the client; otherwise set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details. Use returned references unchanged in ref/root_ref; re-find expired elements.

Record and replay UI scenarios.

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. Actions:

• record_cancel() Cancel user-actions recording (discard the scenario). (1C 8.3.2+)

• record_finish(path=null) Stop recording; return XML in uilog or save path (relative to SERVER working directory; returns absolute). Write failure returns ok=false/error/path AND uilog; recording already stopped, so retry cannot recover it. Synth completion failure returns finish_not_confirmed with preserved XML. lost_actions means incomplete replay. no_effect lists unchanged readbacks by CALL index, not XML step; not proof of no effect. observed/not_observed count successful/unavailable readbacks; readback/scope describe coverage. Empty no_effect with observed=0 means nothing checked. (1C 8.3.2+)

• record_pause() Pause user-actions recording: actions performed until tc_scenario(action="record_resume") stay out of the scenario. (1C 8.3.2+)

• record_resume() Resume user-actions recording. (1C 8.3.2+)

• record_start() Start recording a scenario (uilog) that tc_scenario(action="run_scenario") can replay later. Perform the real, effect-producing actions between start and tc_scenario(action="record_finish"), then read the scenario from finish. (1C 8.3.2+)

• run_scenario(uilog=null, path=null, result_mode='summary') Replay uilog XML or path on the current form. Unsupported steps are skipped/listed; first failure stops at 0-based stopped_at. total counts reported steps, played counts attempted steps including failures. ok means all attempted commands accepted, not all effects verified; full steps[].changed follows each action's contract. Default summary; result_mode=full adds steps. Logs retain full details in both modes. Set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details.

Search the UI tree for objects.

• marks a required action parameter; the group schema treats action parameters as optional. Pass action="name" and only that action's parameters. Actions:

• find_object(name=null, cls=null, type=null, root_ref=null, title=null, timeout=0, scope='window') Find the first object matching the criteria (parameters as in tc_find(action="find_objects")). When nothing matched, the answer carries the same filter diagnostics as tc_find(action="find_objects"). (1C 8.3.3+)

• find_objects(name=null, cls=null, type=null, root_ref=null, title=null, timeout=0, scope='window', limit=null, cursor=null) Search UI objects: name/title support * ?; cls/type use discovered class/platform kind (tc_app(action="get_child_objects")). root_ref defaults to active window; scope=application requires omitting it. timeout retries while no matches (0: once). Empty results are ok; cls/type diagnostics identify unknown filters and list observed kinds. Windows/command buttons include url when available. No limit returns all; limit=1..1000 pages with total/has_more/next_cursor. Continue with cursor alone (plus connection_id if needed), no filters. Pages retain the original result for 5 minutes; elements may become stale. (1C 8.3.3+)

• wait_for_object_displayed(name=null, cls=null, type=null, title=null, timeout=60) Poll the UI tree until an object matching the criteria appears, up to timeout seconds. Returns the object, or ok=False on timeout. Criteria as in tc_find(action="find_objects"). On timeout the answer says whether a cls was seen at all and lists the classes that were actually present, so a misspelled class name is distinguishable from an object that never appeared. (1C 8.3.3+) root_ref selects the client; otherwise set connection_id when several clients are connected. Use tc_session(action="list_connections"). Success may omit target/connection echoes and shorten window details. Use returned references unchanged in root_ref; re-find expired elements.