Metadata-Version: 2.4
Name: hw-test
Version: 2.3.0
Summary: Hardware compatibility testing tool for ALT Linux (based on pc-test / Basalt SPo methodology)
Author-email: Pavel Shilov <zerospirit@altlinux.org>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/zerospirit79/hw-test
Project-URL: Repository, https://github.com/zerospirit79/hw-test
Project-URL: Documentation, https://www.basealt.ru/product-compatibility
Keywords: altlinux,hardware,testing,compatibility,benchmark
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Benchmark
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9.0
Requires-Dist: py-cpuinfo>=9.0.0
Requires-Dist: packaging>=21.0
Requires-Dist: pexpect>=4.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Dynamic: license-file

# HW-TEST

hw-test предназначена для упрощения и автоматизации прохождения тестирования
оборудования на совместимость с ОС Альт по соответствующей методике. Текущая
версия hw-test автоматизирует разделы методики: 5-10.1, 10.2.1-10.2.3, 10.6.2,
10.8, 10.9 (без изменения состояния BMC), 10.11, 11.1 и 11.2, помогает пройти
10.4, 10.10.3, 10.10.7, 10.10.10 и 10.10.12 (с фиксацией результата
тестировщиком), формирует черновик протокола (`protocol.md`, `protocol.html`),
а также доустанавливает пакеты, необходимые для всего процесса тестирования.
Актуальную версию методики тестирования компьютеров всегда можно найти
на [этой странице](https://www.basealt.ru/product-compatibility#c2278).
Теперь она включена ещё и в состав пакета `hw-test-doc` в формате HTML5.

## Системные требования

hw-test поддерживает [регулярные сборки](https://www.altlinux.org/Regular)
на основе Сизифа и [стартовые наборы](https://www.altlinux.org/Starterkits),
а также [официально выпущенные](https://getalt.org/ru/) дистрибутивы
[ООО «Базальт СПО»](https://www.basealt.ru/) на основе бранчей p9, p10, p11,
c9f1, c9f2, c10f1 и c10f2, включая дистрибутивы «Альт СП», сертифицированные
в ФСТЭК России, вплоть до Альт СП «релиз 10» (10.2.1).

## Возможности hw-test

* обновление ОС и установка пакетов из публичных Интернет репозиториев;
* обновление ОС и установка пакетов из публичных архивов p9, p10, p11,
  c9f2, c10f2 и Сизифа;
* обновление ОС и установка пакетов с зеркала на подключаемом носителе;
* обновление ОС и установка пакетов с зеркала в локальной сети;
* автоматизировано переключение на требуемый репозиторий;
* автоматизировано обновление ОС сразу после развёртывания;
* поддерживаются специальные процедуры обновления Альт СП, вплоть до
  Альт СП «релиз 10» (10.2.1);
* автоматизирован сбор информации об ОС и оборудовании;
* конфигурирование тестов в графическом и текстовом режимах;
* имеется возможность доустановки графики на Альт СП Сервер «релиз 10»;
* поддерживается пакетный режим запуска программы с полным отказом от
  ручного конфигурирования и ввода данных (`--batch`);
* полностью автоматизировано прохождение некоторых тестов;
* имеется возможность повторно пройти ранее пройденный тест;
* поддерживаются две локали: русская и англо-американская.

Программа не предназначена для обновления продуктовых систем с большим
числом накопленных проблем. Нельзя гарантировать успех обновления во всех
случаях для репозитория Сизиф ввиду его нестабильности. Например, процедура
обновления не сможет выполнить переход на UsrMerge или автоматически решить
проблемы файловых или пакетных конфликтов, если с этим не справился APT. См.:

* https://www.altlinux.org/Usrmerge
* https://www.altlinux.org/Branches/Sisyphus#Ошибки_обновления

## Установка программы

Перед установкой программы нужно убедиться, что используется самая последняя
версия RPM-пакета. Проверить и скачать самую актуальную версию можно здесь:

https://packages.altlinux.org/ru/sisyphus/srpms/hw-test/rpms/

Сразу после окончания установки ОС Альт (раздел 4 методики) и возможного
применения необходимых воркэраундов из раздела 12.2 методики, программа
устанавливается следующей командой:

```bash
$ su-
# rpm -ivh [http://сервер]/путь/к/hw-test-версия-релиз.noarch.rpm
```

При этом минимально необходимые зависимости, скорее всего, обеспечиваются
чистой, только что установленной системой. Здесь важно, что, в отличии от
традиционного подхода к установке пакетов в ОС Альт, нет необходимости
предварительно настраивать репозиторий и обновлять индексы. Программа
реализована на **Python 3** (ядро, шаги тестирования, GUI и экспресс-тест).
Исходные bash-скрипты шагов удалены; Python-код — в `python3/hw_test/` (устанавливается в `%python3_sitelibdir`), l10n — в `usr/libexec/hw-test/l10n/`.
RPM-пакет требует `python3`; остальные зависимости для тестов
устанавливаются по ходу выполнения. В случае
возникновения проблем можно воспользоваться вторым способом установки:

```bash
$ su-
# apt-get update
# apt-get install [http://сервер]/путь/к/hw-test-версия-релиз.noarch.rpm
```

При таком варианте минимально необходимые зависимости будут доустановлены
из подключенного репозитория установочного диска либо Интернет репозитория.
Ещё один, более простой способ установки — из специального кармана:

```bash
$ su-
# apt-repo test 348515
```

## Запуск программы

До запуска программы необходимо извлечь из компьютера все не относящиеся
к тестированию носители информации, отключить другие устройства, которые
не должны проходить тестирование по методике.

Программу следует запускать под обычным пользователем, если он существует,
чтобы иметь возможность выполнять тесты в сеансе обычного пользователя.
В этом случае будет настроена `sudo` для выполнения операций, требующих
привелегий `root`. Программу следует запускать в эмуляторе терминала
графического сеанса, при его доступности, а если графика не установлена,
тогда уже в текстовом терминале. При запуске программы под пользователем
`root` или в текстовом терминале, число охвачиваемых тестов уменьшается,
не пройденные тесты блокируются.

```bash
$ hw-test
```

После выполнения некоторых операций, таких, как обновление ядра или фирменной
прошивки, компьютер перезагружается, хотя тестирование ещё не было завершено.
При работе в **графическом сеансе** hw-test будет запускаться автоматически
(файл `~/.config/autostart/hw-test.desktop`) до окончания первой фазы тестирования.

На **системах без графики** (ALT Server, консоль/SSH) автопродолжение работает
по тому же принципу, что и в графике: после reboot достаточно **войти** под
тестовым пользователем — `/etc/profile.d/hw-test-resume.sh` запускает
`hw-test --continue`, если есть маркер `~/HW-TEST/STATE/RESUME_ON_LOGIN`
(его создаёт hw-test перед перезагрузкой). Вводить команду вручную не нужно.

Аналогия с графикой:

| Среда | Что включает автопродолжение |
|-------|------------------------------|
| Workstation / DE | вход в сеанс → `~/.config/autostart/hw-test.desktop` |
| Server / без GUI | вход в TTY или SSH → `/etc/profile.d/hw-test-resume.sh` |

По умолчанию режим включён (`headless_autorun` не задан). Отключение:
`headless_autorun=0` в `/etc/hw-test.conf` или запуск с `--no-autorun`.

Если автопродолжение не сработало (нет маркера, неинтерактивный shell), вручную:

```bash
$ hw-test --continue
```

Проверка:

```bash
ls ~/HW-TEST/STATE/RESUME_ON_LOGIN
less -r ~/HW-TEST/hw-test.log
```

Если автозапуск в графическом сеансе не срабатывает ожидаемым образом, т.е.
после очередной перезагрузки окно эмулятора терминала с hw-test не появляется,
а в журнале есть фатальная ошибка, следует использовать ключ `--no-autorun`,
который запретит автозапуск. Для возобновления тестирования после такой ошибки
запустите вручную hw-test с ключом `--continue` (`-C`) из эмулятора терминала.

В случае крупного обновления в графическом сеансе, если вдруг закроется окно
эмулятора терминала или произойдёт выход из сеанса пользователя, достаточно
возобновить тестирование с той же точки, запустив hw-test с ключом `--continue`
(`-C`). Такое замечено, например, в среде KDE Plasma при нехватке памяти.

После тестирования вручную по разделам 10 и 11.3 методки, нужно запустить
hw-test ещё раз с параметром `--finish` (`-F`). При этом выполняется финальная
стадия сборки журналов (раздел 10.11 методики), а в домашнем каталоге текущего
пользователя создаётся архив вида `hw-test-ГГГГ-ММ-ДД.tar` с результатами
тестирования. При наличии каталога или символьной ссылки `/mnt/hw-test`, архив
переносится в этот каталог под именем `/mnt/hw-test/<ИМЯ_ТЕСТА>-ГГГГ-ММ-ДД.tar`,
где `ИМЯ_ТЕСТА` определяется автоматически и может изменяться через командную
строку параметром `--name` (`-n`). Дата начала тестирования также может быть
изменена параметром `--date` (`-d`), причём данный параметр предписывает
использовать ещё и архив публичного репозитория на заданную дату.

На подкаталог с результатами тестирования указывает символьная ссылка `HW-TEST`
в домашнем каталоге пользователя. Результаты ручного тестирования можно также
складывать в подкаталог `HW-TEST`. Журнал тестирования можно посмотреть такой
командой:

```bash
$ less -r ~/HW-TEST/hw-test.log
```

## Прохождение экспресс-теста

При наличии одновременно одного проводного сетевого адаптера и одного
беспроводного, нужно настроить и проверить работу Wi-Fi, затем подключить
сетевой кабель и убедиться, что работает проводная сеть. Также необходимо
предварительно настроить браузер на обычную работу — все вкладки закрыты,
при запуске не задаётся вопросов про настройку бумажника, восстановление
сеанса, итп. Если заведомо известно, что не работает «спящий» или «ждущий»
режим, его необходимо заблаговременно замаскировать: `systemctl mask
{suspend|hibernate}.target`, иначе экспресс-тест будет провален. Только
после этого запускается hw-test.

Когда дойдёте до раздела 9, компьютер будет выключен. Предлагается на
этом месте включить видеозапись происходящего. Очень важно дальше ничего
не нажимать, ничего не трогать и не двигать, если конкретных действий не
будет предложено выполнить вручную, так как экспресс-тест теперь полностью
автоматизирован. В самом конце этого теста, до перезагрузки, даётся 40 секунд
на ручную демонстрацию работы функциональных клавиш, других аудио и видео
устройств вывода. Видеозапись следует выключить сразу после завершения работы
ОС, когда компьютер уходит на перезагрузку.

Браузер выбирается автоматически единственный имеющийся или предпочитаемый.
Видео для воспроизведения выбирается случайным образом из более 135 сэмплов.
В файле конфигурации можно определить собственный сэмпл (`local_video_sample`)
либо выбрать один из наборов видео (`express_video_set`): youtube, rutube,
vkvideo или определённый пользователем.

## Тонкая настройка

Для массового тестирования однотипных компьютеров, одного компьютера с разными
дистрибутивами ОС Альт, для использования локального зеркала репозитория, для
определения собственной цветовой палитры и других параметров, можно определить
свою конфигурацию в `/etc/hw-test.conf`, детали есть в комментариях внутри
этого файла. Данный файл конфигурации не заменяется при установке пакета.

В конфиге `/etc/hw-test-<VSET>.txt` можно определить собственный набор коротких
ссылок на видео «VSET» в таком же формате, как `/var/lib/hw-test/youtube.txt`,
а в конфиге `/etc/hw-test-RVSETS.txt` переопределить шаблоны полных ссылок на
видео, как в файле `/var/lib/hw-test/rvsets.txt`.

Конфигурационные файлы с такими же именами могут размещаться в домашнем каталоге
пользователя (`~/.config/hw-test-<VSET>.txt` и `~/.config/hw-test-RVSETS.txt`),
им отдаётся предпочтение при наличии, но конфиг `~/.config/hw-test.conf` всегда
используется вместе с глобальной конфигурацией.

## Внешний вид

![07](img/07.png "Тестирование завершено, Регулярная сборка на Сизифе")

[Другие скриншоты работы с программой](img/pictures.md).

## Получение справки

```bash
$ hw-test --help
```

Обратите внимание: локаль и ключи запуска программы определяются только в
самом начале тестирования. При последующих запусках hw-test менять локаль
и другие опции бесполезно.

Сообщайте об ошибках на https://bugzilla.altlinux.org/

Удачного тестирования! ;-)
