From e644becf857e3d9aa34ba4ac30af76cb87560fd5 Mon Sep 17 00:00:00 2001 From: sipayrt Date: Mon, 1 Jul 2024 16:24:01 +0300 Subject: [PATCH] docs: add info about migration from hermione --- .../how-to-upgrade-hermione-to-testplane.mdx | 74 +++++++++++++++++++ .../current.json | 4 + .../how-to-upgrade-hermione-to-testplane.mdx | 72 ++++++++++++++++++ 3 files changed, 150 insertions(+) create mode 100644 docs/migrations/how-to-upgrade-hermione-to-testplane.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/migrations/how-to-upgrade-hermione-to-testplane.mdx diff --git a/docs/migrations/how-to-upgrade-hermione-to-testplane.mdx b/docs/migrations/how-to-upgrade-hermione-to-testplane.mdx new file mode 100644 index 0000000..5108a7d --- /dev/null +++ b/docs/migrations/how-to-upgrade-hermione-to-testplane.mdx @@ -0,0 +1,74 @@ +import Admonition from "@theme/Admonition"; + +# Как обновить Hermione до Testplane + + +Если в вашем проекте Hermione младше 8-й версии, то прочтите сначала: +* «[Как обновить hermione до версии 4.x][how-to-upgrade-hermione-to-4]»; +* «[Как обновить hermione до версии 5.x][how-to-upgrade-hermione-to-5]»; +* «[Как обновить hermione до версии 6.x][how-to-upgrade-hermione-to-6]»; +* «[Как обновить hermione до версии 7.x][how-to-upgrade-hermione-to-7]»; +* «[Как обновить hermione до версии 8.x][how-to-upgrade-hermione-to-8]». + +Мы рекомендуем вам обновлять Hermione поэтапно, убеждаясь на каждом этапе, что все тесты проекта корректно выполняются. + + + +## Что изменилось? {#what_is_new} + +Этот проект ранее назывался Hermione, но со временем возникли некоторые проблемы с авторскими правами и товарными знаками, что привело к решению о ребрендинге. После некоторого обсуждения мы остановились на Testplane в качестве официального нового названия. +Так как это изменение является простым ребрендингом, мы продолжили сквозное версионирование, вместо того, чтобы начинать версионирование заново. Таким образом, Testplane@8.x является простой заменой Hermione@8.x. +Testplane имеет полную обратную совместимость c Hermione — умеет читать конфиги Hermione, поддерживает ее плагины, а для более плавного переезда экспортирует сразу 2 bin-файла (testplane и hermione). + +## Как переехать? {#how_to_move} + +### 1. Заменить npm-зависимости `hermione` на `testplane` в package.json {#uninstall_hermione} + +```bash +npm uninstall hermione +npm install -D testplane +``` + +### 2. В вашем ts-конфиге `tsconfig.json` заменить поле `hermione` на `testplane` {#update_ts_config} + +```javascript +{ + "compilerOptions": { + "types": [ + "testplane" + ] + } +} +``` + +### 3. Заменить все импорты и декларации пакета hermione (при наличии) {#remove_from_code} + +- `import ... from "hermione"` → `import ... from "testplane"` +- `require("hermione")` → `require("testplane")` +- `declare module "hermione"` → `declare module "testplane"` + +### 4. Опциональные изменения (не обязательны для переезда, но рекомендованные) {#optional_changes} + +- при запуске используйте bin-файл `testplane` вместо `hermione`; +- переименуйте файл конфигурации `.hermione.conf.(t|j)s` в `.testplane.conf.(t|j)s`; +- используйте глобальный хелпер `globalThis.testplane` вместо `globalThis.hermione`; +- для переопределения конфига используйте переменные окружения, начинающиеся на `testplane_` вместо `hermione_`; +- используйте поле `testplane` вместо `hermione` в обработчиках событий; +- для тайпингов используйте [TestplaneCts][tp-ctx] вместо `HermioneCtx`; +- для получения контекста в тесте используйте свойство браузера `executionContext.testplaneCtx` вместо `executionContext.hermioneCtx`; +- если вы используете дефолтное значение опции [screenshotsDir][screenshotsdir], то переименуйте папку со скриншотами "hermione/screens" в "testplane/screens" иил явно укажите в конфиге значение; +- если вы используете дефолтное значение опции [sets.files][sets], то переименуйте вашу папку с тестами "hermione → testplane" или укажите явно значение опции. + +## Поддержка {#support} + +Если при переезде вы столкнетесь с проблемами или у вас возникнут какие-либо вопросы, то приходите в [github issues][gh-issues] — и мы обязательно вам поможем! + +[how-to-upgrade-hermione-to-4]: ../migrations/how-to-upgrade-hermione-to-4 +[how-to-upgrade-hermione-to-5]: ../migrations/how-to-upgrade-hermione-to-5 +[how-to-upgrade-hermione-to-6]: ../migrations/how-to-upgrade-hermione-to-6 +[how-to-upgrade-hermione-to-7]: ../migrations/how-to-upgrade-hermione-to-7 +[how-to-upgrade-hermione-to-8]: ../migrations/how-to-upgrade-hermione-to-8 +[tp-ctx]: https://github.com/gemini-testing/testplane/blob/master/docs/typescript.md#testplanectx-typings +[screenshotsdir]: https://github.com/gemini-testing/testplane/blob/master/docs/config.md#https://github.com/gemini-testing/testplane/blob/master/docs/config.md#screenshotsdir +[sets]: https://github.com/gemini-testing/testplane/blob/master/docs/config.md#sets +[gh-issues]: https://github.com/gemini-testing/testplane/issues/ diff --git a/i18n/en/docusaurus-plugin-content-docs/current.json b/i18n/en/docusaurus-plugin-content-docs/current.json index da01697..4ab9139 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current.json +++ b/i18n/en/docusaurus-plugin-content-docs/current.json @@ -11,6 +11,10 @@ "message": "HTML Reporter", "description": "The label for category HTML Reporter in sidebar mainSidebar" }, + "sidebar.mainSidebar.category.Migrations": { + "message": "Migrations", + "description": "The label for category Migrations in sidebar mainSidebar" + }, "sidebar.mainSidebar.category.Plugins": { "message": "Plugins", "description": "The label for category Plugins in sidebar mainSidebar" diff --git a/i18n/en/docusaurus-plugin-content-docs/current/migrations/how-to-upgrade-hermione-to-testplane.mdx b/i18n/en/docusaurus-plugin-content-docs/current/migrations/how-to-upgrade-hermione-to-testplane.mdx new file mode 100644 index 0000000..375dca7 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/migrations/how-to-upgrade-hermione-to-testplane.mdx @@ -0,0 +1,72 @@ +import Admonition from "@theme/Admonition"; + +# How to migrate from Hermione to Testplane + + +If in your project Hermione is younger than the v8.x version, then read first: +* «[How to update hermione to the v.4.x][how-to-upgrade-hermione-to-4]»; +* «[How to update hermione to the v.5.x][how-to-upgrade-hermione-to-5]»; +* «[How to update hermione to the v.6.x][how-to-upgrade-hermione-to-6]»; +* «[How to update hermione to the v.7.x][how-to-upgrade-hermione-to-7]»; +* «[How to update hermione to the v.8.x][how-to-upgrade-hermione-to-8]». + +We recommend updating Hermione step by step, ensuring at each stage that all project tests are executed correctly. + + + +## What has changed? {#what_is_new} + +This project was formerly known as "Hermione", but eventually some copyright and trademark issues surfaced, leading to the decision to rebrand. After some discussion, we settled on "Testplane" as the official new title. Considering this change as merely a rebranding, we've proceeded with the existing version count instead of starting anew. Thus, Testplane `v8.x` is a drop-in replacement for Hermione `v8.x`. + +## How to move? {#how_to_move} + +### 1. Replace hermione deps with tesplane in `package.json` {#uninstall_hermione} + +```bash +npm uninstall hermione +npm install -D testplane +``` + +### 2. Replace "hermione" with "testplane" in compilerOptions.types field of your tsconfig.json file {#update_ts_config} + +```javascript +{ + "compilerOptions": { + "types": [ + "testplane" + ] + } +} +``` + +### 3. Replace all imports, requires and declarations {#remove_from_code} + +- `import ... from "hermione"` → `import ... from "testplane"` +- `require("hermione")` → `require("testplane")` +- `declare module "hermione"` → `declare module "testplane"` + +### 4. Optional changes list (these are not required, but recommended) {#optional_changes} + +- use `testplane` binary instead of `hermione` binary; +- rename `.hermione.conf.ts`, `.hermione.conf.js` configs to `.testplane.conf.ts`, `.testplane.conf.js`; +- use `globalThis.testplane` helper instead of `globalThis.hermione`; +- use `testplane_` environment variables instead of `hermione_` environment variables; +- use testplane field instead of hermione on event handlers; +- use [TestplaneCtx][tp-ctx] instead of `HermioneCtx` type; +- use `executionContext.testplaneCtx` as browser property instead of `executionContext.hermioneCtx`; +- if you use default [screenshotsDir][screenshotsdir] value, rename "hermione/screens" directory to "testplane/screens" or specify the value "hermione/screens" explicitly; +- if you use default [sets.files][sets] value, move your tests from "hermione" to "testplane" directory or specify the value "hermione" explicitly. + +## Support {#support} + +If you encounter any problems during the migration or have any questions, come to [github issues][gh-issues] - and we will definitely help you! + +[how-to-upgrade-hermione-to-4]: ../migrations/how-to-upgrade-hermione-to-4 +[how-to-upgrade-hermione-to-5]: ../migrations/how-to-upgrade-hermione-to-5 +[how-to-upgrade-hermione-to-6]: ../migrations/how-to-upgrade-hermione-to-6 +[how-to-upgrade-hermione-to-7]: ../migrations/how-to-upgrade-hermione-to-7 +[how-to-upgrade-hermione-to-8]: ../migrations/how-to-upgrade-hermione-to-8 +[tp-ctx]: https://github.com/gemini-testing/testplane/blob/master/docs/typescript.md#testplanectx-typings +[screenshotsdir]: https://github.com/gemini-testing/testplane/blob/master/docs/config.md#https://github.com/gemini-testing/testplane/blob/master/docs/config.md#screenshotsdir +[sets]: https://github.com/gemini-testing/testplane/blob/master/docs/config.md#sets +[gh-issues]: https://github.com/gemini-testing/testplane/issues/