Автоматически Unit Test Пример кода

Моя команда отвечает за разработку API для большой системы, которую мы также пишем. Нам нужно предоставить примерный код, чтобы другие разработчики, использующие наш API, могли узнать, как его использовать. Мы документировали код, используя комментарии к документу xml. например.

/// <summary>Summary here</summary>
/// <example>Here is an example  <code>example code here</code> </example>
public void SomeFunction()

Затем мы используем Sandcastle и создаем необходимые файлы справки (chm и онлайн-сайт).

Это довольно неловко, когда код примера не работает, и обычно это происходит из-за изменения некоторых функций или простой ошибки.

Кто-нибудь когда-либо делал что-то подобное, но также настраивал модульные тесты для запуска на примере кода, чтобы они, как известно, работали во время сборки?

Ответ 1

Да, sandcastle поддерживает это, и это здорово поддерживать правильность примеров. Вы можете указать область кода следующим образом:

   /// <summary>
   /// Gizmo which can act as client or server.
   /// </summary>
   /// <example>
   /// The following example shows how to use the gizmo as a client:
   /// <code lang="cs"
   ///    source="..\gizmo.unittests\TestGizmo.cs"
   ///    region="GizmoClientSample"/>
   /// </example>
   public class Gizmo

Затем вы можете использовать некоторый тестовый код в TestGizmo.cs в качестве примера, заключая его в область:

[Test]
public GizmoCanActAsClient()
{
   #region GizmoClientSample
   Gizmo gizmo = new Gizmo();
   gizmo.ActAsClient();
   #endregion
}

Предостережение. Если вы переместите или переименуте тестовый файл, вы получите сообщение об ошибке при попытке восстановить документацию с помощью sandcastle.

Ответ 2

Я бы предложил использовать специальный бит разметки в вашем XML, который гласит: "Возьмите образец кода из этого места". Он будет ссылаться на обычный файл С#, который можно запустить с помощью модульных тестов. Чтобы взять ваш пример, вы можете:

/// <summary>Summary here</summary>
/// <example>Here is an example
/// <code>!!sourcefile:SomeClassTest.cs#SomeFunction!!</code></example>
public void SomeFunction()

Тестирование вашего устройства выполняется как обычно, а затем вставить шаг сборки между "create XML" и "run Sandcastle", который вы заменили бы каждый "токен файла" соответствующим содержимым. Там могут быть даже крючки, которые вы можете поместить в Sandcastle, чтобы сделать это во время создания doc - я не знаю достаточно о Sandcastle, чтобы точно знать.

Уродливо придумывать свою собственную разметку, но она должна работать.

Конечно, это предполагает, что примеры кода легко проверяются на единицу - некоторые могут не быть (если они имеют дело с ресурсами и т.д.). По крайней мере, вы знаете, что он компилируется, хотя:)

Ответ 3

Простое решение: Сделайте небольшое приложение, в которое вы включаете все заголовки примерных кодов, а затем вызывайте их соответствующие точки входа

#include "samples/sampleA.h"

void main()
{
  SomeFunction();
}

то после того, как вы выполните сборку этих маленьких приложений, вам нужно убедиться, что они побежали нормально. Но можете ли вы проверить, что код работает нормально, если у кого-то нет вечеринки с сервером NightlyBuild?

Лучшее решение: Зарегистрируйте выход и попросите кого-нибудь посмотреть его утром.

Даже лучшее решение: Запишите вывод и grep его или что-то, поэтому никто не должен смотреть на него, если его не сломал.

Лучшее решение: Найдите подходящую тестовую структуру, надеюсь, что-нибудь со всеми звонками и свистами, которые вы можете получить, чтобы он мог отправлять электронные сообщения людям, если их сломал или что-то в этом роде. В нашем случае мы избегаем колоколов и свистов, вместо этого мы подключаем Полицейскую сирену USB, которая отключается, когда что-то ломается. Это довольно интересно!

Ответ 4

Я не делал этого сам, но я видел это в книгах Прагматического программиста. Если я не ошибаюсь, книга "Прагматическое тестирование единицы в С# с Nunit" упоминает, что они сделали это для книги. Возможно, они упомянули в одном из своих подкастов.

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