Merge pull request #39 from gemini-testing/TESTPLANE-246.add_vscode_e…

…xtension_article

chore: write article about vscode extension

blog/vscode-extension.mdx

@@ -0,0 +1,130 @@
+---
+title: Расширение для VS Code
+slug: vscode-extension
+hide_table_of_contents: false
+date: 2024-09-26T19:00
+---
+
+import Admonition from "@theme/Admonition";
+import runTestsFromSidebarVideoUrl from "/video/blog/vscode-extension/run-tests-from-sidebar.mp4";
+import runTestsFromEditorVideoUrl from "/video/blog/vscode-extension/run-tests-from-editor.mp4";
+
+Для Testplane реализовали расширение для [VS Code][vscode], с помощью которого можно настраивать Testplane с нуля, запускать тесты и удобно работать с <a href="/ru/docs/v8/command-line/#testplane-repl">REPL режимом</a>.
+
+<!-- truncate -->
+
+### Установка
+
+Установите расширение со страницы [VS Code Marketplace][vscode-testplane-marketplace] или на вкладке расширений в VS Code IDE.
+
+![Расширение в VS Code IDE](/img/blog/vscode-extension/testplane-in-extensions-panel.png)
+
+После установки откройте VS Code в пустом проекте и в панеле управления введите:
+
+```
+Install Testplane
+```
+
+![Установка Testplane](/img/blog/vscode-extension/testplane-install.png)
+
+### Запуск тестов
+
+#### Из сайдбара в панеле для тестирования
+
+Панель для тестирования можно открыть, кликнув на значок тестирования в панели действий.
+
+![Открытие панели для тестирования](/img/blog/vscode-extension/testing-sidebar.png)
+
+В левой части экрана отображается сайдбар с деревом всех прочитанных тестов. В дереве сверху вниз отображаются:
+
+-   название директории с тестами (`testplane-tests`);
+-   название файла теста (`example.testplane.ts`);
+-   название сьюта (`test`). В примере используется `describe` из [Mocha BDD интерфейса][mocha-bdd-interface];
+-   название теста (`example`). В примере использует `it` из [Mocha BDD интерфейса][mocha-bdd-interface];
+-   название браузера в котором тест будет запущен (`chrome`).
+
+У каждого из элементов дерева отображается кнопка `Run Test`. Если нажать на `Run Test` у элемента:
+
+-   директории, файла или сьюта, то запустятся все дочерние тесты во всех браузерах;
+-   теста, то запустится выбранный тест во всех браузерах;
+-   браузера, то запустится один тест в одном браузере.
+
+Пример запуска тестов из сайдбара:
+
+<video src={runTestsFromSidebarVideoUrl} width="100%" controls="controls">
+    Тег video не поддерживается вашим браузером.
+    <a href="video/blog/vscode-extension/run-tests-from-sidebar.mp4">Скачайте видео</a>.
+</video>
+
+Также можно выполнить запуск всех тестов с помощью кнопки `Run Tests`.
+
+![Запуск всех тестов](/img/blog/vscode-extension/run-all-tests-from-sidebar.png)
+
+#### Из текстового редактора
+
+Если в текстовом редакторе открыть Testplane тест, то рядом с каждым сьютом (`describe`) и тестом (`it`) будет отображаться зеленая кнопка play для их запуска. Если нажать левой кнопкой мыши, то запустится тест во всех браузерах, и после его выполнения отобразится результат в виде иконки статуса прохождения теста.
+Если нажать на кнопку play правой клавишей мыши, то можно запустить тест в одном из браузеров.
+
+Пример запуска тестов из текстового редактора:
+
+<video src={runTestsFromEditorVideoUrl} width="100%" controls="controls">
+    Тег video не поддерживается вашим браузером.
+    <a href="video/blog/vscode-extension/run-tests-from-editor.mp4">Скачайте видео</a>.
+</video>
+
+#### С настройкой `devtools`
+
+В сайдбаре в панели для тестирования так же отображается секция с названием Testplane. В ней можно управлять настройками в рантайме. При клике в чекбокс `Enable devtools` и последующем запуске тестов браузеры будут подниматься с использованием CDP протокола (вне зависимости от того что указано в конфиге). Подробнее про этот режим можно прочитать <a href="/ru/docs/v8/guides/how-to-use-cdp/">тут</a>.
+
+![Включение опции devtools](/img/blog/vscode-extension/enable-devtools.png)
+
+#### С настройкой `REPL`
+
+При клике в чекбокс `Enable REPL` и последующем запуске теста (в REPL режиме можно одновременно запустить только один тест) он будет запущен в специальном REPL режиме. Подробнее про этот режим можно прочитать <a href="/ru/docs/v8/command-line/#testplane-repl">тут</a>.
+
+![Включение опции REPL](/img/blog/vscode-extension/enable-repl.png)
+
+### Фильтрация тестов в сайдбаре панели тестирования
+
+Чтобы в дереве отобразить только тесты в определенном браузере, необходимо ввести тег `@testplane:browser:your_browser_name` в инпут фильтрации. Чтобы появился саджест, можно просто написать `@browser`. Там же можно использовать несколько тегов.
+
+![Фильтр по указанном браузеру](/img/blog/vscode-extension/filter_sidebar_by_browser.png)
+
+Также в инпуте с фильтрацией можно использовать следующие значения:
+
+-   строка с названием элемента дерева (директория/файл/сьют/тест/браузер);
+-   тег `@doc` - для отображения тестов из активного файла в текстовом редакторе;
+-   тег `@openedFiles` - для отображения тестов во всех открытых файлах в текстовом редакторе;
+-   тег `@executed` - для отображения только выполняющихся тестов;
+-   тег `@failed` - для отображения только упавших тестов.
+
+### Перезапуск окружения Testplane
+
+С помощью кнопки `Refresh Tests` в сайдбаре можно перезапустить Testplane. В этом случае перечитается конфиг и тесты. Пригодится в случае, если вы добавили новый тест в файл (вотчинг тестовых файлов пока не поддерживается) или произошла какая-то критическая ошибка.
+Обновление дерева тестов выполняется автоматически при изменении конфига.
+
+![Обновление дерева тестов](/img/blog/vscode-extension/refresh-tests.png)
+
+### Требования
+
+-   версия testplane должна быть 8.20.0 и старше (с версиями ниже запуск тестов работать не будет).
+
+### Текущие ограничения
+
+-   не поддержаны debug и continuous (auto-run) режимы;
+-   нет вотчинга добавления/удаления тестов и файлов;
+-   использование кастомных интерфейсов Mocha может приводить к некорректному отображению иконок с кнопкой play для запуска тестов из текстового редактора.
+
+### Заключение
+
+Данная функциональность предоставляет нашим пользователям новые возможности:
+
+-   возможность запуска тестов прямо из IDE и просмотр результата выполнения;
+-   возможность максимально быстро переключится в режим `devtools` и `repl`;
+-   автоматически подхватывать изменения, внесенные в конфиг Testplane.
+
+Устанавливайте расширение Testplane для VS Code и приходите с фидбеком. В случае обнаружения проблем приходите в [issue github](https://github.com/gemini-testing/testplane/issues) — мы вам обязательно поможем!
+
+[vscode]: https://code.visualstudio.com/
+[vscode-testplane-marketplace]: https://marketplace.visualstudio.com/items?itemName=gemini-testing.vscode-testplane
+[mocha-bdd-interface]: https://mochajs.org/#bdd

i18n/en/docusaurus-plugin-content-blog/vscode-extension.mdx

@@ -0,0 +1,129 @@
+---
+title: Extension for VS Code
+slug: vscode-extension
+hide_table_of_contents: false
+date: 2024-09-26T19:00
+---
+
+import Admonition from "@theme/Admonition";
+import runTestsFromSidebarVideoUrl from "/video/blog/vscode-extension/run-tests-from-sidebar.mp4";
+import runTestsFromEditorVideoUrl from "/video/blog/vscode-extension/run-tests-from-editor.mp4";
+
+We have implemented an extension for [VS Code][vscode] for Testplane, which allows you to configure Testplane from scratch, run tests, and conveniently work with the <a href="/ru/docs/v8/command-line/#testplane-repl">REPL mode</a>.
+
+<!-- truncate -->
+
+### Installation
+
+Install the extension from the [VS Code Marketplace][vscode-testplane-marketplace] or from the extensions tab in the VS Code IDE.
+
+![Extension in VS Code IDE](/img/blog/vscode-extension/testplane-in-extensions-panel.png)
+
+After installation, open VS Code in an empty project and enter in the command panel:
+
+```
+Install Testplane
+```
+
+![Install Testplane](/img/blog/vscode-extension/testplane-install.png)
+
+### Running tests
+
+#### From the sidebar in the testing panel
+
+The testing panel can be opened by clicking on the testing icon in the activity bar.
+
+![Opening testing panel in activity bar](/img/blog/vscode-extension/testing-sidebar.png)
+
+On the left side of the screen, a sidebar displays a tree of all read tests. The tree displays from top to bottom:
+
+-   the name of the directory with tests (`testplane-tests`);
+-   the name of the test file (`example.testplane.ts`);
+-   the name of the suite (`test`). In the example, `describe` from the [Mocha BDD interface][mocha-bdd-interface] is used;
+-   the name of the test (`example`). In the example, `it` from the [Mocha BDD interface][mocha-bdd-interface] is used;
+-   the name of the browser in which the test will be run (`chrome`).
+
+Each element in the tree has a `Run Test` button. If you click on it at the element:
+
+-   for a directory, file, or suite, all child tests will run in all browsers;
+-   for a test, the selected test will run in all browsers;
+-   for a browser, one test will run in one browser.
+
+Example of running tests from the sidebar:
+
+<video src={runTestsFromSidebarVideoUrl} width="100%" controls="controls">
+    The video tag is not supported by your browser.
+    <a href="video/blog/vscode-extension/run-tests-from-sidebar.mp4">Download the video</a>.
+</video>
+
+You can also run all tests using the `Run Tests` button.
+
+![Running all tests](/img/blog/vscode-extension/run-all-tests-from-sidebar.png)
+
+#### From a text editor
+
+If you open a Testplane test in the text editor, a green play button will be displayed next to each suite (`describe`) and test (`it`) for launching them. If you click the left mouse button, the test will run in all browsers, and after execution, the result will be displayed as a status icon for the test's pass/fail status.
+If you right-click the play button, you can run the test in one of the browsers.
+
+Example of running tests from a text editor:
+
+<video src={runTestsFromEditorVideoUrl} width="100%" controls="controls">
+    The video tag is not supported by your browser.
+    <a href="video/blog/vscode-extension/run-tests-from-editor.mp4">Download the video</a>.
+</video>
+
+#### With the `devtools` settings
+
+In the sidebar of the testing panel, there is also a section titled Testplane. Here you can manage settings at runtime. By clicking the `Enable devtools` checkbox and subsequently running tests, browsers will launch using the CDP protocol (regardless of what is specified in the config). You can read more about this mode <a href="/en/docs/v8/guides/how-to-use-cdp/">here</a>..
+
+![Enabling devtools option](/img/blog/vscode-extension/enable-devtools.png)
+
+#### With the `REPL` settings
+
+When you click the checkbox `Enable REPL` and subsequently run a test (only one test can be run simultaneously in REPL mode), it will be launched in a special REPL mode. You can read more about this mode <a href="/ru/docs/v8/command-line/#testplane-repl">here</a>.
+
+![Enabling the REPL option](/img/blog/vscode-extension/enable-repl.png)
+
+### Filtering tests in the sidebar of the testing panel
+
+To display only tests in a specific browser in the tree, you need to enter the tag `@testplane:browser:your_browser_name` in the filtering input. To get a suggestion, you can simply type `@browser`. You can also use multiple tags there.
+
+![Filter by specified browser](/img/blog/vscode-extension/filter_sidebar_by_browser.png)
+
+You can also use the following values in the filter input:
+
+-   a string with the name of the tree element (directory/file/suite/test/browser);
+-   tag @doc - to display tests from the active file in the text editor;
+-   tag @openedFiles - to display tests in all open files in the text editor;
+-   tag @executed - to display only running tests;
+-   tag @failed - to display only failed tests.
+
+### Restarting the Testplane Environment
+
+You can restart Testplane using the `Refresh Tests` button in the sidebar. In this case, the config and tests will be re-read. This will be useful if you have added a new test to a file (watching test files is not yet supported) or if a critical error has occurred. The test tree is automatically updated when the config changes.
+
+![Updating the test tree](/img/blog/vscode-extension/refresh-tests.png)
+
+### Requirements
+
+-   the Testplane version must be 8.20.0 or higher (tests will not run with lower versions).
+
+### Current Limitations
+
+-   debug and continuous (auto-run) modes are not supported;
+-   there is no watching for adding/removing tests and files;
+-   using custom Mocha interfaces may lead to incorrect display of icons with the play button for running tests from the text editor.
+
+### Conclusion
+
+This functionality provides our users with new opportunities:
+
+-   the ability to run tests directly from the IDE and view the execution results;
+-   the ability to quickly switch to devtools and REPL mode;
+-   automatically pick up changes made to the Testplane config.
+
+Install the Testplane extension for VS Code and provide us with feedback. If you encounter any issues, please visit the [GitHub issue](https://github.com/gemini-testing/testplane/issues) — we will definitely help you!
+
+[vscode]: https://code.visualstudio.com/
+[vscode-testplane-marketplace]: https://marketplace.visualstudio.com/items?itemName=gemini-testing.vscode-testplane
+[mocha-bdd-interface]: https://mochajs.org/#bdd