Пример кода автоматического модульного теста

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

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

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

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

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


unit-testing .net sandcastle
person Chris Aitchison    schedule 19.11.2008    source источник

Ответы (4)


arrow_upward
8
arrow_downward

Да, 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.

person Wim Coenen    schedule 02.03.2009

arrow_upward
9
arrow_downward

Я бы посоветовал использовать в вашем XML специальный фрагмент разметки, который гласит: «Возьмите образец кода отсюда». Это будет относиться к обычному файлу C #, который можно запускать с помощью модульных тестов. Если взять ваш пример, у вас может быть:

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

Ваши модульные тесты выполняются как обычно, а затем вставьте этап сборки между «создать XML» и «запустить Sandcastle», вы замените каждый «токен файла» соответствующим содержимым. Могут быть даже крючки, которые вы можете вставить в Sandcastle, чтобы сделать это во время создания документа - я недостаточно знаю о Sandcastle, чтобы знать наверняка.

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

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

person Jon Skeet    schedule 19.11.2008
comment
Я создал проект для этого: code.google.com/p/addsourcetodocumentation - person khebbie; 01.12.2008
comment
Sandcastle имеет встроенную поддержку для этого. Смотрите мой собственный ответ. - person Wim Coenen; 04.03.2009

arrow_upward
0
arrow_downward

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

#include "samples/sampleA.h"

void main()
{
  SomeFunction();
}

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

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

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

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

person Robert Gould    schedule 19.11.2008

arrow_upward
0
arrow_downward

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

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

person Mendelt    schedule 19.11.2008