godotengine/godot-docs-l10n
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs-l10n.git synced 2025-12-31 09:49:22 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
65104565532c1cd1d239cc7b9237aff838ac7274
godot-docs-l10n/sphinx/templates/engine_details/architecture/unit_testing.pot
Rémi Verschelde 6510456553 Sync Sphinx and Weblate templates with current docs (4.6)
2025-12-19 15:00:42 +01:00

539 lines
23 KiB
Plaintext
Raw Blame History

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0)
# This file is distributed under the same license as the Godot Engine package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Godot Engine latest\n"
"Report-Msgid-Bugs-To: \n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#: ../../docs/engine_details/architecture/unit_testing.rst:4
msgid "Unit testing"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:6
msgid "Godot Engine allows to write unit tests directly in C++. The engine integrates the `doctest <https://github.com/doctest/doctest>`_ unit testing framework which gives ability to write test suites and test cases next to production code, but since the tests in Godot go through a different ``main`` entry point, the tests reside in a dedicated ``tests/`` directory instead, which is located at the root of the engine source code."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:14
msgid "Platform and target support"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:16
msgid "C++ unit tests can be run on Linux, macOS, and Windows operating systems."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:18
msgid "Tests can only be run with editor ``tools`` enabled, which means that export templates cannot be tested currently."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:22
msgid "Running tests"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:24
msgid "Before tests can be actually run, the engine must be compiled with the ``tests`` build option enabled (and any other build option you typically use), as the tests are not compiled as part of the engine by default:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:32
msgid "Once the build is done, run the tests with a ``--test`` command-line option:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:38
msgid "The test run can be configured with the various doctest-specific command-line options. To retrieve the full list of supported options, run the ``--test`` command with the ``--help`` option:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:46
msgid "Any other options and arguments after the ``--test`` command are treated as arguments for doctest."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:51
msgid "Tests are compiled automatically if you use the ``dev_mode=yes`` SCons option. ``dev_mode=yes`` is recommended if you plan on contributing to the engine development as it will automatically treat compilation warnings as errors. The continuous integration system will fail if any compilation warnings are detected, so you should strive to fix all warnings before opening a pull request."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:59
msgid "Filtering tests"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:61
msgid "By default, all tests are run if you don't supply any extra arguments after the ``--test`` command. But if you're writing new tests or would like to see the successful assertions output coming from those tests for debugging purposes, you can run the tests of interest with the various filtering options provided by doctest."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:67
msgid "The wildcard syntax ``*`` is supported for matching any number of characters in test suites, test cases, and source file names:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:71
msgid "**Filter options**"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:71
msgid "**Shorthand**"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:71
msgid "**Examples**"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:73
msgid "``--test-suite``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:73
msgid "``-ts``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:73
msgid "``-ts=\"*[GDScript]*\"``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:75
msgid "``--test-case``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:75
msgid "``-tc``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:75
msgid "``-tc=\"*[String]*\"``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:77
msgid "``--source-file``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:77
msgid "``-sf``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:77
msgid "``-sf=\"*test_color*\"``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:80
msgid "For instance, to run only the ``String`` unit tests, run:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:86
msgid "Successful assertions output can be enabled with the ``--success`` (``-s``) option, and can be combined with any combination of filtering options above, for instance:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:94
msgid "Specific tests can be skipped with corresponding ``-exclude`` options. As of now, some tests include random stress tests which take a while to execute. In order to skip those kind of tests, run the following command:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:103
msgid "Writing tests"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:105
msgid "Test suites represent C++ header files which must be included as part of the main test entry point in ``tests/test_main.cpp``. Most test suites are located directly under ``tests/`` directory."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:109
msgid "All header files are prefixed with ``test_``, and this is a naming convention which the Godot build system relies on to detect tests throughout the engine."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:112
msgid "Here's a minimal working test suite with a single test case written:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:130
msgid "You can quickly generate new tests using the ``create_test.py`` script found in the ``tests/`` directory. This script automatically creates a new test file with the required boilerplate code in the appropriate location. It's also able to automatically include the new header in ``tests/test_main.cpp`` using invasive mode (``-i`` flag). To view usage instructions, run the script with the ``-h`` flag."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:135
msgid "The ``tests/test_macros.h`` header encapsulates everything which is needed for writing C++ unit tests in Godot. It includes doctest assertion and logging macros such as ``CHECK`` as seen above, and of course the definitions for writing test cases themselves."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:142
msgid "`tests/test_macros.h <https://github.com/godotengine/godot/blob/master/tests/test_macros.h>`_ source code for currently implemented macros and aliases for them."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:145
msgid "Test cases are created using ``TEST_CASE`` function-like macro. Each test case must have a brief description written in parentheses, optionally including custom tags which allow to filter the tests at runtime, such as ``[String]``, ``[Stress]`` etc."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:150
msgid "Test cases are written in a dedicated namespace. This is not required, but allows to prevent naming collisions for when other static helper functions are written to accommodate the repeating testing procedures such as populating common test data for each test, or writing parameterized tests."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:155
msgid "Godot supports writing tests per C++ module. For instructions on how to write module tests, refer to :ref:`doc_custom_module_unit_tests`."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:159
msgid "Subcases"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:161
msgid "In situations where you have a common setup for several test cases with only slight variations, subcases can be very helpful. Here's an example:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:175
msgid "Each ``SUBCASE`` causes the ``TEST_CASE`` to be executed from the beginning. Subcases can be nested to an arbitrary depth, but it is advised to limit nesting to no more than one level deep."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:179
msgid "Assertions"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:181
msgid "A list of all commonly used assertions used throughout the Godot tests, sorted by severity."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:185
msgid "**Assertion**"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:185
#: ../../docs/engine_details/architecture/unit_testing.rst:218
#: ../../docs/engine_details/architecture/unit_testing.rst:272
msgid "**Description**"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:187
msgid "``REQUIRE``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:187
msgid "Test if condition holds true. Fails the entire test immediately if the condition does not hold true."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:189
msgid "``REQUIRE_FALSE``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:189
msgid "Test if condition does not hold true. Fails the entire test immediately if the condition holds true."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:191
msgid "``CHECK``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:191
msgid "Test if condition holds true. Marks the test run as failing, but allow to run other assertions."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:193
msgid "``CHECK_FALSE``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:193
msgid "Test if condition does not hold true. Marks the test run as failing, but allow to run other assertions."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:195
msgid "``WARN``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:195
msgid "Test if condition holds true. Does not fail the test under any circumstance, but logs a warning if something does not hold true."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:197
msgid "``WARN_FALSE``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:197
msgid "Test if condition does not hold true. Does not fail the test under any circumstance, but logs a warning if something holds true."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:200
msgid "All of the above assertions have corresponding ``*_MESSAGE`` macros, which allow to print optional message with rationale of what should happen."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:203
msgid "Prefer to use ``CHECK`` for self-explanatory assertions and ``CHECK_MESSAGE`` for more complex ones if you think that it deserves a better explanation."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:208
msgid "`doctest: Assertion macros <https://github.com/doctest/doctest/blob/master/doc/markdown/assertions.md>`_."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:211
msgid "Logging"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:213
msgid "The test output is handled by doctest itself, and does not rely on Godot printing or logging functionality at all, so it's recommended to use dedicated macros which allow to log test output in a format written by doctest."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:218
msgid "**Macro**"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:220
msgid "``MESSAGE``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:220
msgid "Prints a message."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:222
msgid "``FAIL_CHECK``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:222
msgid "Marks the test as failing, but continue the execution. Can be wrapped in conditionals for complex checks."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:224
msgid "``FAIL``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:224
msgid "Fails the test immediately. Can be wrapped in conditionals for complex checks."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:227
msgid "Different reporters can be chosen at runtime. For instance, here's how the output can be redirected to an XML file:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:236
msgid "`doctest: Logging macros <https://github.com/doctest/doctest/blob/master/doc/markdown/logging.md>`_."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:239
msgid "Testing failure paths"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:241
msgid "Sometimes, it's not always feasible to test for an *expected* result. With the Godot development philosophy of that the engine should not crash and should gracefully recover whenever a non-fatal error occurs, it's important to check that those failure paths are indeed safe to execute without crashing the engine."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:246
msgid "*Unexpected* behavior can be tested in the same way as anything else. The only problem this creates is that the error printing shall unnecessarily pollute the test output with errors coming from the engine itself (even if the end result is successful)."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:251
msgid "To alleviate this problem, use ``ERR_PRINT_OFF`` and ``ERR_PRINT_ON`` macros directly within test cases to temporarily disable the error output coming from the engine, for instance:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:267
msgid "Special tags in test case names"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:269
msgid "These tags can be added to the test case name to modify or extend the test environment:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:272
msgid "**Tag**"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:274
msgid "``[SceneTree]``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:274
msgid "Required for test cases that rely on a scene tree with MessageQueue to be available. It also enables a mock rendering server and :ref:`ThemeDB<class_ThemeDB>`."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:276
msgid "``[Editor]``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:276
msgid "Like ``[SceneTree]``, but with additional editor-related infrastructure available, such as :ref:`EditorSettings<class_EditorSettings>`."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:278
msgid "``[Audio]``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:278
msgid "Initializes the :ref:`AudioServer<class_AudioServer>` using a mock audio driver."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:280
msgid "``[Navigation2D]``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:280
msgid "Creates the default 2D navigation server and makes it available for testing."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:282
msgid "``[Navigation3D]``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:282
msgid "Creates the default 3D navigation server and makes it available for testing."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:285
msgid "You can use them together to combine multiple test environment extensions."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:288
msgid "Testing signals"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:290
msgid "The following macros can be use to test signals:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:296
msgid "Macro"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:297
msgid "Description"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:298
msgid "``SIGNAL_WATCH(object, \"signal_name\")``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:299
msgid "Starts watching the specified signal on the given object."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:300
msgid "``SIGNAL_UNWATCH(object, \"signal_name\")``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:301
msgid "Stops watching the specified signal on the given object."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:302
msgid "``SIGNAL_CHECK(\"signal_name\", Vector<Vector<Variant>>)``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:303
msgid "Checks the arguments of all fired signals. The outer vector contains each fired signal, while the inner vector contains the list of arguments for that signal. The order of signals is significant."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:304
msgid "``SIGNAL_CHECK_FALSE(\"signal_name\")``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:305
msgid "Checks if the specified signal was not fired."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:306
msgid "``SIGNAL_DISCARD(\"signal_name\")``"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:307
msgid "Discards all records of the specified signal."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:309
msgid "Below is an example demonstrating the use of these macros:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:330
msgid "Test tools"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:332
msgid "Test tools are advanced methods which allow you to run arbitrary procedures to facilitate the process of manual testing and debugging the engine internals."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:335
msgid "These tools can be run by supplying the name of a tool after the ``--test`` command-line option. For instance, the GDScript module implements and registers several tools to help the debugging of the tokenizer, parser, and compiler:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:345
msgid "If any such tool is detected, then the rest of the unit tests are skipped."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:347
msgid "Test tools can be registered anywhere throughout the engine as the registering mechanism closely resembles of what doctest provides while registering test cases using dynamic initialization technique, but usually these can be registered at corresponding ``register_types.cpp`` sources (per module or core)."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:352
msgid "Here's an example of how GDScript registers test tools in ``modules/gdscript/register_types.cpp``:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:375
msgid "The custom command-line parsing can be performed by a test tool itself with the help of OS :ref:`get_cmdline_args<class_OS_method_get_cmdline_args>` method."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:379
msgid "Integration tests for GDScript"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:381
msgid "Godot uses doctest to prevent regressions in GDScript during development. There are several types of test scripts which can be written:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:384
msgid "tests for expected errors;"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:385
msgid "tests for warnings;"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:386
msgid "tests for features."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:388
msgid "Therefore, the process of writing integration tests for GDScript is the following:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:390
msgid "Pick a type of a test script you'd like to write, and create a new GDScript file under the ``modules/gdscript/tests/scripts`` directory within corresponding sub-directory."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:394
msgid "Write GDScript code. The test script must have a function called ``test()`` which takes no arguments. Such function will be called by the test runner. The test should not have any dependency unless it's part of the test too. Global classes (using ``class_name``) are registered before the runner starts, so those should work if needed."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:400
msgid "Here's an example test script:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:408
msgid "Change directory to the Godot source repository root."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:414
msgid "Generate ``*.out`` files to update the expected results from the output:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:420
msgid "You may add the ``--print-filenames`` option to see filenames as their test outputs are generated. If you are working on a new feature that is causing hard crashes, you can use this option to quickly find which test file causes the crash and debug from there."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:425
msgid "Run GDScript tests with:"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:431
msgid "This also accepts the ``--print-filenames`` option (see above)."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:433
msgid "If no errors are printed and everything goes well, you're done!"
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:437
msgid "Make sure the output does have the expected values before submitting a pull request. If ``--gdscript-generate-tests`` produces ``*.out`` files which are unrelated to newly added tests, you should revert those files back and only commit ``*.out`` files for new tests."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:444
msgid "The GDScript test runner is meant for testing the GDScript implementation, not for testing user scripts nor testing the engine using scripts. We recommend writing new tests for already resolved `issues related to GDScript at GitHub <https://github.com/godotengine/godot/issues?q=is%3Aissue+label%3Atopic%3Agdscript+is%3Aclosed>`_, or writing tests for currently working features."
msgstr ""
#: ../../docs/engine_details/architecture/unit_testing.rst:452
msgid "If your test case requires that there is no ``test()`` function present inside the script file, you can disable the runtime section of the test by naming the script file so that it matches the pattern ``*.notest.gd``. For example, \"test_empty_file.notest.gd\"."
msgstr ""
Reference in New Issue View Git Blame Copy Permalink