Слияние кода завершено, страница обновится автоматически
Сначала пожалуйста ознакомьтесь с кодексом поведения Hyperledger перед участием.
Есть много способов участия в проекте Hyperledger Cacti как пользователю, так и разработчику.
Как пользователь, это может включать:
Как разработчик:
Мы приветствуем вклады в этот проект в различных формах, будь то исправление ошибки, улучшение документации, добавление новой функции или поддержка нового платформенного слоя распределённой книги транзакций (DLT).Пожалуйста, ознакомьтесь с документацией. В частности, просмотрите концепцию и методологию проектирования и системную архитектуру. Следуйте указаниям учебника для тестирования Cactus и Weaver соответственно. (Для более глубокого понимания концепции и спецификаций Weaver также проверьте RFC Weaver.)## Основы работы с Git / Читательская программа
Эта секция предназначена для вас, если вы не знакомы со сложными концепциями Git, такими как
Слово о спорной теме форсирующего вливания:
В большинстве руководств по Git можно прочитать, что форсирующее вливание запрещено практически всегда.
Это верно в 99% случаев, НО если вы единственный человек, работающий над веткой (что обычно верно для вашей ветки функциональности или исправления, которое вы планируете представить в виде запроса на вливание), то форсирующее вливание не просто допустимо, но и необходимо для избежания запутанных логов коммитов Git.
Вопрос, который вам следует задать себе перед форсирующим вливанием, следующий: Будет ли моё действие уничтожать работу других людей на удалённой ветке? Если никто другой не работает над этой веткой, ответ, конечно же, отрицательный, и форсирующее вливание может использоваться безопасно. Если же другие работают вместе с вами над одной и той же веткой, считается вежливо предупредить их заранее перед форсирующим вливанием, чтобы они могли принять необходимые меры предосторожности с их стороны тоже.Полезный инструмент для предотвращения случайного уничтожения работы других — это новый функционал Git, называемый --force-with-lease:
Использование git push --force-with-lease вместо простого --force настоятельно рекомендуется: https://softwareengineering.stackexchange.com/a/312710
Документация rustlang включает отличное описание и дополнительные ссылки практически на всё, что вам нужно знать.
Единственная разница между требованиями к пулл-реквестам у них и у Cacti заключается в том, что мы поощряем людей ссылаться на задачи в GitHub в сообщениях коммитов.
Цитирую наиболее значимые части ниже (и благодарю поддерживателей Rust за это):
Внесение изменений в Rust осуществляется главным образом через pull request. Сам GitHub имеет отличную документацию по использованию функции Pull Request. Мы используем модель «fork and pull», описанную здесь, где участники проекта отправляют изменения в свой личный fork и создают pull requests для внесения этих изменений в основной репозиторий.
Пожалуйста, направляйте pull requests против основной ветки.
Rust следует политике запрета слияния, что означает, что при возникновении конфликтов слияния вы должны всегда использовать rebase вместо слияния. Например, всегда используйте rebase при приведении последних изменений из основной ветки в вашу ветку с новыми функциями. Также убедитесь, что исправленные коммиты объединены в связанные коммиты с осмысленными сообщениями о коммите.> GitHub позволяет закрывать задачи с помощью ключевых слов. Эта функция должна использоваться для поддержания чистоты трекера задач.## Проверка списка PR — участник/разработчик Чтобы избежать проблем в будущем, не устанавливайте зависимости глобально. Убедитесь, что все зависимости находятся в автономном режиме.
GitHub Desktop или другие.```shell
git config --global core.longpaths true
2. Клонируйте форк на ваш локальный компьютер.
3. (Необязательно) [Создайте локальную ветку](#create-local-branch) для минимизации конфликтов кода при желании вносить несколько изменений относительно разных проблем параллельно.
4. Выполните необходимые изменения и где возможно протестируйте локально.
1. Вы можете запустить полный набор CI тестов на Mac/Linux/WSL, выполнив скрипт в `/tools/ci.sh`.
2. Если вы не настроили среду для выполнения bash-скриптов, не беспокойтесь, все pull-requests автоматически будут иметь тот же скрипт выполнен для него при открытии. Единственный недостаток — это более медленный обратный путь.
5. Убедитесь, что вы настроили свои подписи Git.
1. Примечание: всегда подписывайте свои коммиты с помощью `git commit -S`.
2. Для получения дополнительной информации см. [здесь](https://gist.github.com/tkuhrt/10211ae0a26a91a8c030d00344f7d11b).
6. Подумайте/определите, как будет выглядеть ваш коммит-сообщение.
1. Синтаксис коммит-сообщения может быть трудным для запоминания, поэтому мы приглашаем вас использовать команду `npm run commit`, которая при выполнении предлагает вам последовательность вопросов, которые можно заполнить, а также проверяет ваши ответы в реальном времени, делая невозможным (или по крайней мере намного сложнее) создание некорректного сообщения коммита, которое бот проверки коммитов на GitHub отметит ошибкой.Использование этого инструмента вышеописано является полностью опциональным в случае необходимости помощи.
2. Примечание: выполнение команды `npm run commit` попытается выполнить фактический коммит в конце, если процесс не будет прерван с помощью `Ctrl + C` или аналогичным действием в вашей терминальной системе.
3. Команда `npm run commit` также попытается подписать созданный коммит, так что убедитесь, что она правильно настроена перед использованием.
7. Внесите ваши изменения
1. Убедитесь, что ваше коммит-сообщение соответствует требованиям форматирования (подробности выше) и здесь: [синтаксис Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4/#specification); это помогает в генерации заметок выпуска, которую мы планируем автоматизировать.
2. Будьте осведомлены, что мы используем git-commit-hooks для автоматизации некоторых рутинных задач, таких как применение требуемого стиля кода и форматирования, так что ваш код будет автоматически завершён каждую строку до 80 символов. Если вы хотите увидеть, как ваши изменения будут отформатированы, можно запустить команду `npm run prettier` в терминале или установить расширение для интегрированной среды разработки (IDE) для инструмента `Prettier`, который сделает то же самое (расширение для VSCode известно своей работоспособностью).8\. Убедитесь, что ваша ветка переходит на основную ветку `upstream/main`, где `upstream` — это сложная терминология Git для основной ветки проекта Cacti на GitHub (та, с которой вы создали свой форк).
1\. **Не** дублируйте свой запрос на слияние после того, как он был проверен. Дублирование здесь означает закрытие существующего PR и затем открытие нового, который больше не содержит историю проверки. Если вы столкнулись с проблемами управления версионностью, которых не знаете, как решить, поддерживатели будут рады помочь вам, чтобы вы не были вынуждены открывать новый запрос на слияние с нуля.
1\. Единственным исключением из этого правила является случай, если вы ошибочно назвали свою ветку специальными символами и таким образом оказались в состоянии, когда стало невозможно отправить изменения на удаленный сервер из-за этого (что случалось раньше с названиями веток типа `refactor(core-api): x`, которые пришлось переименовать в `refactor-core-api-x`, а затем создать новый PR).
2\. Если у вас возникли проблемы, есть множество отличных ресурсов, доступных онлайн (поэтому мы не будем писать еще один здесь).
1\. Если вы имеете трудности с поиском подходящего руководства конкретно по механике переотделки, мы можем порекомендовать [это](https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history). Благодарим Рафаэля за ссылку! 2\. Если вы прошли через этот учебник и всё ещё не совсем уверены, что происходит, попробуйте также этот: <https://about.gitlab.com/blog/2020/11/23/keep-git-history-clean-with-interactive-rebase/>
3\. Если возникают конфликты слияния, вы должны исправить эти конфликты во время переотделки, так как пропуск этого шага не делает конфликты автоматически исчезающими, просто передаёт их дальше на поддержку, которая попытается выполнить слияние вашего запроса на более позднем этапе. 4\. Если вышеупомянутое произошло, в этом случае поддерживатель скорее всего попросит вас (если до этого не делал этого) выполнить переотделку, поскольку как автор изменений вы наилучшим образом располагаете информацией для решения любых конфликтов на уровне кода. Иногда поддерживаемые лица могут выполнить слияние/разрешение конфликтов самостоятельно, но не полагайтесь на это и не привыкайте рассчитывать на возможное великодушие.
5\. После успешной переотделки внимательно просмотрите ваши коммиты. Оптимально должно быть один коммит в каждом запросе на получение, однако с другой стороны каждый коммит должен быть как можно меньше, простым и самодостаточным, поэтому могут возникнуть ситуации, когда имеет смысл отправить запрос на получение с несколькими коммитами, если, например, вам также пришлось что-то изменить в тестовых инструментах во время реализации функциональности (в этом случае может быть коммит за функциональность самой по себе и ещё один за необходимые изменения в пакете тестовых инструментов). Однако мы просим вас стараться избегать таких ситуаций и отправлять большинство своих запросов на получение с одним, самодостаточным коммитом, который не затрагивает несколько вещей.Это значительно снижает когнитивную нагрузку, связанную с проверкой изменений, что в свою очередь делает всех счастливее: поддерживаемые лица будут иметь более легкую задачу проверки, что означает, что они будут выполнять эту работу быстрее, что, вероятнее всего, вызовет у вас радость.9. Отправьте ваши изменения в ваш основной (или в ту ветку функциональности, которую вы выбрали, это полностью зависит от вас) репозиторий.
10. Инициируйте запрос на получение из вашего форка в основной репозиторий.
6. Помните: Открытие запроса на получение — это как сказать "Привет, поддерживаемые лица, у меня есть этот изменённый вариант, готовый для того, чтобы вы потратили время на его проверку". Здесь слово "готовый" означает, что вы не планируете больше ничего менять на этой ветке, кроме случаев, когда вас попросят сделать это рецензенты.
7. Полностью допустимо открыть запрос на получение и пометить его как "черновик" (функция GitHub), что сигнализирует поддерживаемым лицам, что если у них есть время, они могут посмотреть на изменение, но оно может быть или нет в своём окончательном виде, так что вы не будете ответственны за потери времени со стороны других, если проверка придётся выполнять несколько раз из-за изменений. Как только вы продвинете свой черновик до настоящего запроса на получение, применимы вышеупомянутые замечания.8. Если ваш запрос на получение содержит значительное изменение, мы рекомендуем добавить аналогичную метку GitHub к нему. Если вы этого не сделаете, и мы заметим, что изменение действительно значительное, мы добавим метку. Однако, если вы это сделаете заранее, это скорее всего ускорит процесс, убрав один этап общения из процедуры проверки вашего запроса на слияние.11. Подождать завершения CI, проверок соответствия DCO и линтера, а также любых замечаний от рецензентов.
12. Если вам нужно обновить ваш запрос на слияние либо потому что вы обнаружили проблему, либо потому что вас попросили сделать это, мы просим вас:
9. попробуйте внести изменения таким образом, чтобы они не создавали дополнительных коммитов в вашем запросе на слияние, но вместо этого выполните команду `git commit --amend --signoff` на вашей локальной ветке, а затем выполните force-push на удаленной ветке (ваш запрос на слияние). Вновь, если изменения, которые вы вносите, не могут быть включены в существующие коммиты вашего запроса на слияние, то добавление нового коммита может быть оправдано, и это зависит от вашего усмотрения (сохранители могут вежливо попросить вас сгруппировать коммиты, если они видят иначе).
10. Примерное правило для всех вещей в git/Cacti заключается в том, чтобы поддерживать чистую и аккуратную историю коммитов, которая позволяет всем легко находить изменения и получать точные ответы на базовые вопросы типа "Кто?", "Что?", "Когда?" и "Почему?". Если вы когда-либо оказывались в ситуации, когда пытаетесь понять, где была введена первоначальная ошибка (и пытались понять, почему был внесен этот вредный коммит), а команда git-blame привела вас к патчу размером cq 10 мегабайт с сообщением "слияние xyz", тогда вы точно знаете, что именно мы стараемся избежать здесь. :-)
**Исправленные моменты:**
- Удалены лишние пробелы после запятых.
- Корректно оформлены знаки препинания.
- Сохранено оригинальное форматирование.Примечание: DCO - Сертификат Происхождения Разработчика, CI - Непрерывная Интеграция. ## Список проверок PR — Модератор/Проверяющий
Убедитесь, что все следующие условия выполнены (в дополнение к вашему согласию с самой правкой):1. Все автоматизированные проверки, которые здесь явно не указаны, также проходят успешно/зелёные.
2. Ветка переходит на основную ветку `main` и нет лишних/повторяющихся коммитов.
3. Коммиты выглядят простыми и автономными. Простота всегда относительна к масштабу самого изменения, конечно. Изменение в 1000 строк может быть всё равно простым, если оно состоит всего лишь в переименовании некоторых часто используемых переменных там, где они используются.
4. Если вкладчики испытывают трудности с базовой функциональностью Git, такой как ребейзинг / форси-пушинг, DCO, сделайте всё возможное, чтобы помочь им. Когда есть сомнения, не стесняйтесь обращаться к Петеру (который является тем самым, кто требует всех этих правил Git, поэтому он заслуживает быть первичной контактной точкой для всех вопросов, связанных с Git).
1. Помните, что мы хотим способствовать приветливому сообществу, так что если кто-то новичок в Git, будьте особенно терпеливы к нему в этом аспекте.
5. Убедитесь, что сообщения коммитов соответствуют стандартному формату.
1. Помните, что если вы выбрали "слияние" на пользовательском интерфейсе GitHub при принятии запроса на слияние, GitHub (по умолчанию) предложит использовать название запроса на слияние как новое сообщение коммита для вашего слияния.Это хорошо только в том случае, если название действительно является допустимым сообщением коммита, но в случае, когда это не так, вам следует особенно позаботиться о том, чтобы правильно ввести допустимое сообщение коммита прямо там и тогда на пользовательском интерфейсе GitHub.
2. Чтобы избежать хлопот/потенциальных проблем с вышеупомянутым, рекомендуется всегда использовать "rebase" при принятии запроса на слияние, даже если есть несколько коммитов, которые вы бы предпочли видеть слитыми.
3. Если вы настаиваете на том, чтобы не принимать PR с несколькими коммитами, это вполне понятно и справедливо. Рекомендованный подход заключается в том, чтобы попросить вкладчика разделить запрос на слияние на несколько запросов на слияние, выполнив интерактивный rebase на его ветке и отобрав/перестроив вещи соответственно. Это довольно продвинутый случай использования Git, так что вы можете захотеть помочь ему с этим (или обратиться к Петеру, который постоянно нудит всем об этих правилах Git...).Чтобы защитить исходный код Hyperledger Cacti, GitHub принимает запросы на слияние только из форкнутых репозиториев. Здесь также определены и документированы стандарты качества, которые будут улучшаться со временем. ## Создайте локальную ветку
> Каждый раз, когда вы начинаете работу над новым функционалом или исправлением ошибки, важно создать новую ветку.
1. Клонируйте ваш форк на свой локальный компьютер
2. Настройте ваш локальный форк для синхронизации (необязательно)
```bash
# Добавьте репозиторий 'upstream' в список удалённых репозиториев
git remote add upstream https://github.com/hyperledger/cacti.git
# Убедитесь, что новый удалённый репозиторий назван 'upstream'
git remote -v
# Перейдите в основную ветку и выполните rebase до upstream.
# Выполните эти команды всякий раз, когда хотите синхронизировать с основной веткой
git fetch upstream
git checkout main
git rebase upstream/main
# Перейдите в основную ветку — вы хотите, чтобы ваша новая ветка была от основной
git checkout main
``` # Создайте новую ветку с именем `<новая_функция>` (выберите простое информативное имя)
git branch <новая_функция>
git checkout <новая_функция>
git rebase main
# Приятного программирования!
yarn run tools:install-pre-commit-secret-detection
# Теперь pre-commit будет запускаться автоматически при выполнении команды `git commit`
# Подтвердите и отправьте ваши изменения в ваш форк
git add -A
git commit -s -m "<тип>[опциональный диапазон]: <описание>"
git push origin <новая_функция>
git commit --amend, так как ваши изменения будут отправлены автоматически.ЗАМЕЧАНИЕ: Вы можете обратиться к оригинальному руководству 'GitHub Standard Fork & Pull Request Workflow'.
Когда вы начнете использовать свои коды в Hyperledger Cacti, следует следовать структуре директорий Hyperledger Cacti. Текущая структура директорий описана ниже:
- contrib/: Вклады от каждого участника, которые непосредственно не зависят от кода Cacti.
- Fujitsu-ConnectionChain/
- Accenture-BIF/
- IBM-Weaver/
- docs/
- API/
- business-logic-plugin.md
- ledger-plugin.md
- routing-interface.md
- examples/
- example01-car-trade/
- src/
- plugins/
- business-logic-plugin/
- lib/: Библиотеки для создания плагина Business Logic Plugin
- ledger-plugin/: Коды плагина Ledger Plugin
- (ledger-name)/: Включает название реестра (например, Ethereum, Fabric, ...)
- verifier/
- src/: Исходные коды верификатора в плагине Ledger Plugin
- unit-test/: Исходные коды юнит-тестирования верификатора в плагине Ledger Plugin (одиночный драйвер / драйвер и окружение Docker / ...)
- validator/
- src/: Исходные коды валидатора в плагине Ledger Plugin
- unit-test/: Исходные коды юнит-тестирования валидатора в плагине Ledger Plugin (одиночный драйвер / драйвер и окружение Docker / ...)
- routing-interface/
- whitepaper/
- test/
- docker-env/
- kubernetes-env/
Мы стремимся автоматизировать процесс разработки везде, где это возможно, а значительная часть этого связана с автоматическим тестированием, конечно же.
Каждый раз при внесении изменений важно иметь тестовое покрытие для конкретного изменения, которое вы внедряете. Это особенно важно для исправлений ошибок и абсолютно необходимо для изменений/исправлений, связанных с безопасностью.
Написание тестируемых программ очень важно для нас, так как отсутствие такого подхода может (и будет) приводить к накоплению технического долга, который рано или поздно приведёт к снижению качества кода и отпугнет потенциальных участников проекта. Поэтому мы хотим убедиться, что такое развитие событий не произойдет.
Это также означает, что иногда, когда вы делаете изменения, которые кажутся простыми на первый взгляд, вы можете столкнуться с тем, что рецензент вашего запроса на слияние попросит вас сделать дополнительные, казалось бы, не связанные изменения, которые никак не связаны с фактической функцией/ошибкой, которую вы только что реализовали/исправили, но вместо этого они направлены на обеспечение возможности написания тестов для этой функции или связанного кода.Это может показаться хлопотным занятием (ибо это так), но мы просим всех делать всё возможное, чтобы адаптироваться к этому, поскольку это действительно помогает направлять проект на долгосрочной основе.
Один из самых простых примеров вышеупомянутого — когда у вас есть класс, который выполняет какую-либо задачу, и он зависит от общего ресурса для выполнения своей работы. Общий ресурс может быть файловой системой или сетевым портом, открытым для TCP-соединений, например. Вы можете реализовать ваш класс, закрепив номер порта жёстко, и функционально это будет верно (если вы правильно выполнили эту часть) НО если ваш класс не позволяет настраивать указанный порт через конструктор или метод установки, то один из наших более педантичных поддерживателей (например, Петер) сразу обратится к вам с требованием изменить его таким образом, чтобы порт мог быть настроен во время выполнения, позволяя тестовым случаям использовать порт Yöntem, что позволяет запустить тесты параллельно с другими тестами без получения ложноположительных результатов.
Если вы против такой идеи, эти поддерживатели будут радостно ссылаться на этот текст или создавать новое эссе прямо там, на запросе на слияние.
Все тестовые случаи должны быть:
- Самостоятельными программами, которые могут выполняться самостоятельно при необходимости.
- Это гарантирует, что если вы работаете над отдельным тестовым случаем, пытаясь сделать его успешным, у вас всегда будет возможность запустить именно этот один тест вместо выполнения всего набора тестов, время выполнения которого быстро увеличивается по мере добавления тестовых сценариев. Поэтому лучше сразу следовать этому принципу.
- Исключены из открытого API поверхности пакета, в котором они находятся, путём обеспечения того, чтобы тестовые классы/типы/интерфейсы НЕ экспортировались через файл `public-api.ts` данного пакета.
- Единственным исключением является случай, когда пакет сам по себе предназначен для тестирования, как, например, пакет `test-tooling`, название которого указывает на то, что он полностью предназначен для предоставления утилит для написания тестов. В этом случае допускается и даже ожидается, что он будет экспонировать классы/типы связанные с тестированием в своей открытой API поверхности.
Все тестовые случаи должны быть:
- Самостоятельными программами, которые могут выполняться самостоятельно при необходимости.
- Это гарантирует, что если вы работаете над отдельным тестовым случаем, пытаясь сделать его успешным, у вас всегда будет возможность запустить именно этот один тест вместо выполнения всего набора тестов, время выполнения которого быстро увеличивается по мере добавления тестовых сценариев. Поэтому лучше сразу следовать этому принципу.
- Исключены из открытого API поверхности пакета, в котором они находятся, путём обеспечения того, чтобы тестовые классы/типы/интерфейсы НЕ экспортировались через файл `public-api.ts` данного пакета.
- Единственным исключением является случай, когда пакет сам по себе предназначен для тестирования, как, например, пакет `test-tooling`, название которого указывает на то, что он полностью предназначен для предоставления утилит для написания тестов. В этом случае допускается и даже ожидается, что он будет экспонировать классы/типы связанные с тестированием в своей открытой API поверхности.
```Однако следует отметить, что данное правило всё ещё применяется к другим пакетам, то есть ни один пакет не должен зависеть от пакета `test-tooling` как от зависимости npm (`dependency`), а должен объявлять его как зависимость разработчика (`devDependency`) в соответствующем разделе файла `package.json`.
- Совместимы с протоколом [Test Anything Protocol](https://testanything.org/)
- Указанная реализация для NodeJS находится в npm пакете `node-tap`:
- [API утверждений](https://node-tap.org/docs/api/asserts/) Node TAP
- Наиболее простой возможный тестовый случай:
```typescript
const test, { Test } = require("tape");
import * as publicApi from "././././main/typescript/public-api";
``````markdown
- Пример [случайного тестирования](./packages/cactus-test-plugin-consortium-manual/src/test/typescript/integration/plugin-consortium-manual/security-isolation-via-api-server-ports.ts), демонстрирующий всё в действии,
что пропагандируется в этом документе о автоматизации тестирования.
- Основной акцент/проверка одной исправленной ошибки/функции и т. д.
- Ясно разделён от нотест (также известен как `main`) исходного кода.
Это означает практически, что мы просим ваши тестовые случаи либо находятся в
1. дереве `. /src/test/. . .` пакета, который вы проверяете ИЛИ
2. ваши тестовые случаи находятся в дереве `. /src/test/. . .` (да, с тем же именем), но в полностью отдельном пакете, если зависимости требуют этого.
Пример ситуации, когда вам потребуется отдельный тестовый пакет — это если вы разрабатываете плагин реестра, имеющий REST API конечные точки, которые доставляются вместе с ним, и вы хотите проверить в тесте, что плагин может быть загружен в `ApiServer`, а затем вызван через веб-сервис/SDK.
В этом случае вы не можете расположить ваш тестовый случай в пакете плагина реестра, потому что вы хотите избежать необходимости загрузки сервера API как зависимости вашего пакета плагина реестра (чтобы гарантировать, что не будет циклических зависимостей).
Это означает, что для использования среднестатистического ноутбука потребителя, которым обычно располагают люди,
вам потребуется организовать выполнение ваших тестовых случаев параллельно, что сэкономит время всем участникам проекта.
Более быстрое выполнение тестов обеспечивает лучший опыт работы для разработчиков, что делает сообщество нашего открытого проекта более счастливым.
Все это взаимосвязано. ;-)
```- Тестовые случаи не должны зависеть от кода за пределами деревьев каталогов `./src/*` пакетов.
- Не следует полагаться на примеры кода в ваших тестовых случаях.
- Если вам требуется импортировать код, который не является JS/JSON/TS, вы всё равно можете сделать это через соответствующую функцию компилятора TypeScript, которая позволяет импортировать произвольные файлы.
## Работа с кодом
Дополнительные детали можно найти в файле [BUILD.md](./BUILD.md) в корне проекта.
Мы используем Lerna для управления [монорепозиторием](https://blog.npmjs.org/post/186494959890/monorepos-and-npm), который представляет собой Cacti.
> Мы активно используем Docker для тестирования плагинов реестра.
### Выполнение/отладка тестов
Убедитесь, что сборка проходит успешно перед попыткой запустить тесты.
Если вы только что клонировали проект, лучше всего запустить скрипт CI, который выполнит полную сборку и запустит все тесты для вас. Если он завершится ошибкой, вы сможете создать баг-репорт в системе отслеживания проблем.
Предположим, что вы уже выполнили сборку исходного кода, ниже приведены различные способы запуска тестов:
#### Запуск одного тестового случая
Вы выполняете модульные и интеграционные тесты одинаковым образом, но вот примеры для каждого из них отдельно:
- Интеграционный тест: ```sh
yarn jest packages/cactus-test-plugin-consortium-manual/src/test/typescript/integration/plugin-consortium-manual/get-consortrium-jws-endpoint.test.ts
```
- Модульный тест:
```sh
npx jest packages/cactus-common/src/test/typescript/unit/objects/get-all-method-names.test.ts
```
Также вы можете запускать тесты через пользовательский интерфейс Visual Studio Code. Для этого переименуйте файл `template.launch.json` в `launch.json`. В окне "Run and Debug" Visual Studio Code выберите "JEST: Current TS file", чтобы протестировать текущий открытый файл.
#### Запуск всех тестовых случаев (модульные + интеграционные)
```sh
npm run test:all
npm run test:unit
npm run test:integration
npx — это стандартный верхнеуровневый бинарник, который устанавливается в системной переменной PATH при установке NodeJS. Мы используем его для того, чтобы избежать необходимости размещения каждого модуля NodeJS (зависимостей проекта) в системной переменной PATH или глобальной установки этих модулей (npm install some-pkg -g).
Подробнее о npx можно прочитать здесь: https://blog.npmjs.org/post/162869356040/introducing-npx-an-npm-package-runner
Сам Yarn. Например, npx lerna clean становится yarn lerna clean.
.vscode/template.launch.json, скопируйте его с названием launch.json (если у вас ещё нет такого файла) или просто выберите примеры задач отладки Visual Studio Code, которые вам нужны.Для отладки одного тестового случая вам потребуется задача отладки из шаблонного файла template.launch.json, которая называется TAP: Current TS Test File.
Перед запуском этой задачи отладки ваш редактор Visual Studio Code должен быть открыт на тестовом файле, который вы хотите запустить.
При использовании точек останова важно, чтобы вы отлаживали код в том же пакете.> Поддержка карты источников частична на данный момент, но активно работаем над этим.
Если вы работаете над новым соединителем реестра, вам также потребуется образ Docker all-in-one, который обеспечит необходимый уровень автоматизации тестирования. Если поддержщики вашего выбранного реестра предоставляют достаточный образ Docker, то возможно вам не придётся разрабатывать его самостоятельно, хотя это случается крайне редко, поэтому будьте осторожны.
Для просмотра существующего набора примеров для образов besu и quorum обратитесь к папкам tools/docker/besu-all-in-one и tools/docker/corda-all-in-one. Эти образы создают ghcr.io/hyperledger/cactus-besu-all-in-one и ghcr.io/hyperledger/cactus-corda-all-in-one соответственно. Оба используются в тестовых случаях, написанных для конкретных плагинов соединителей реестра:
packages/cactus-plugin-ledger-connector-besu/src/test/typescript/integration/plugin-ledger-connector-besu/deploy-contract/deploy-contract-from-json.test.tsКонкретные классы, которые используют образы all-in-one, расположены в пакете test-tooling по следующим путям:
packages/cactus-test-tooling/src/main/typescript/besu/besu-test-ledger.tsТесты плагинов реестров создаются аналогично другим тестам (хотя это и сложно реализовать, мы стремимся к этому).Единственное отличие между тестовым случаем плагина соединителя реестра и любым другим юнит-тестом заключается в том, что тестовый случай плагина соединителя реестра будет запускать контейнер Docker из одного из образов all-in-one, которые мы поддерживаем как часть Cacti, а затем использовать этот контейнер all-in-one-* для проверки таких вещей, как способность плагина соединителя реестра развернуть контракт на данном реестре.Как общее рекомендованное правило, тестовые случаи никогда не должны переиспользовать любой all-in-one контейнер реестра для выполнения нескольких тестовых случаев, так как это почти наверняка приведёт к нестабильным/дребезжащим тестовым случаям в долгосрочной перспективе и необязательной сложности, зависимостей от порядка и прочего. Рекомендуется, если у вас есть два тестовых случая для плагина соединителя реестра, они оба будут запускать новый созданный контейнер с нуля, выполнять тестовое сценарий и затем полностью разрушать и удалять контейнер.
Пример для плагина соединителя реестра и его автоматизации тестирования, реализованной вышеописанным образом:
packages/cactus-test-plugin-ledger-connector-quorum/src/test/typescript/integration/plugin-ledger-connector-quorum/deploy-contract/deploy-contract-via-web-service.test.ts
Этот тестовый случай также является примером того, как запустить сервер API независимо с одним плагином реестра, что и было предусмотрено при начальной настройке.
Еще один вариант, если вы хотите выполнить некоторые тесты вручную, — запустите сервер API с конфигурацией по вашему выбору:
# Начиная с корневой директории проекта
chmod +x ./packages/cactus-cmd-api-server/dist/lib/main/typescript/cmd/cactus-api.js
./packages/cactus-cmd-api-server/dist/lib/main/typescript/cmd/cactus-api.js --config-file=.config.json
Вы можете запустить этот тестовый случай тем же образом, как и любой другой тестовый случай (что само по себе является требованием для каждого тестового случая).```sh npx tap --ts --timeout=600 packages/cactus-test-plugin-ledger-connector-quorum/src/test/typescript/integration/plugin-ledger-connector-quorum/deploy-contract/deploy-contract-via-web-service.test.ts
Вы можете указать произвольное множество тестовых случаев для выполнения в одном запуске через шаблоны glob. Примеры этих шаблонов glob можно найти в файле `package.json` корневой директории, который содержит npm скрипты для выполнения всех тестов одной командой (скрипт CI использует эти шаблоны):
```json
"test:all": "tap --ts --jobs=1 --timeout=600 \"packages/cactus-*/src/test/typescript/{unit,integration}\"",
"test:unit": "tap --ts --timeout=600 \"packages/cactus-*/src/test/typescript/unit/\"",
"test:integration": "tap --ts --jobs=1 --timeout=600 \"packages/cactus-*/src/test/typescript/integration/\""
Следуя аналогичному шаблону, если у вас есть конкретная папка с тестовыми случаями, вы можете запустить все тесты в этой папке, указав подходящие шаблоны (звездочки и двойные звездочки, как это требуется в зависимости от того, является ли структура папки плоской или имеет подпапки и тесты, расположенные глубоко внутри них).
Например, следующий пример также может работать:
# Начиная с корневого каталога проекта
cd packages/cactus-test-plugin-ledger-connector-quorum/src/test/typescript/integration/plugin-ledger-connector-quorum
npx tap --ts --jobs=1 --timeout=600 "./"
```> Обратите внимание, что шаблоны могут требовать кавычек в некоторых средах командной строки операционной системы, но не обязательно в других. В скриптах npm, используемых Cacti, мы заключаем все шаблоны в кавычки для обеспечения более широкой совместимости со средами.### Создание клиентских библиотек API
Для генерации и компиляции исходного кода клиентских библиотек API вам ничего специального делать не нужно. Все это часть задачи `npm run build:dev:backend`, которую вы можете выполнить самостоятельно или как часть скрипта CI (`./tools/ci.sh`).
Клиентские библиотеки API автоматически генерируются из соответствующего файла `openapi.json` каждого пакета, который предоставляет веб-сервисы (REST/SocketIO/gRPC и т.д.), и могут использоваться другими пакетами при необходимости. Есть отдельный пакет `@hyperledger/cactus-api-client`, предназначенный для хранения общих функциональностей среди остальных клиентских библиотек API. Концепция здесь аналогична абстрактным классам и их реализациям.
Каждый файл `openapi.json` создает свою собственную клиентскую библиотеку API через генератор кода, которая также содержит соответствующие определения моделей, такие как интерфейсы, описывающие тела запросов/ответов всех возможных операций и ограничения проверки данных.
Клиентские библиотеки API спроектированы как универсальные компоненты, то есть они успешно выполняются как в браузере, так и в среде Node.js. Это очень важно, поскольку нам не хочется поддерживать несколько отдельных кодовых баз для различных платформ, а также мы хотим, чтобы как можно больше этого кода было автоматически сгенерировано (в настоящее время это составляет около 100%).
### Добавление новых зависимостей:Пример:
```sh
# Добавляет "got" как зависимость в пакет `@hyperledger/cactus-common`
# Обратите внимание, что вы должны указывать полностью квалифицированное имя пакета,
# как указано в файле package.json
yarn workspace @hyperledger/cactus-common add got --save-exact
Вы должны знать, какой пакет монорепозитория будет использовать этот пакет, а затем выполнить команду yarn workspace с дополнительными параметрами, указывающими имя пакета и имя зависимости.
Дополнительные примеры и подробная информация доступна в официальной документации Yarn Workspaces.
После добавления новых зависимостей вам может потребоваться Перезагрузка окна VSCode после добавления зависимостей
Всегда используйте ключ
--save-exactпри установке новых зависимостей, чтобы гарантировать повторяемость сборки
Если вы добавили новую зависимость и VSCode показывает ошибку при попытке импорта этой зависимости, то иногда проблема заключается в необходимости заставить VSCode перезагрузиться, чтобы он заново проинициализировал TypeScript определения и заметил добавленную зависимость.
Рекомендованный способ сделать это — нажать клавишу F1 (или ту, которая связана с меню команд) и выбрать Developer: Reload Window.
Как альтернатива, вы можете просто завершить работу и перезапустить приложение VSCode.### О повторяемости сборок
Как лучшая практика, любое конкретное редакционное состояние (хэш коммита) должно производить точно такие же сборочные артефакты, независимо от времени или места выполнения сборки. Это возможно только если версии зависимостей npm заморожены и не автоматически обновляются npm (что делает сборку зависимой от времени и машины).
Основной вывод: не используйте синтаксис ^, ~ и * при объявлении ваших зависимостей npm.
Дополнительные детали:
Вы можете оставить комментарий после Вход в систему
Неприемлемый контент может быть отображен здесь и не будет показан на странице. Вы можете проверить и изменить его с помощью соответствующей функции редактирования.
Если вы подтверждаете, что содержание не содержит непристойной лексики/перенаправления на рекламу/насилия/вульгарной порнографии/нарушений/пиратства/ложного/незначительного или незаконного контента, связанного с национальными законами и предписаниями, вы можете нажать «Отправить» для подачи апелляции, и мы обработаем ее как можно скорее.
Опубликовать ( 0 )