Added setters for fox environment variables.

Setting environment variables will override the setter values, but this
will provide a work around to xcodebuild test not passing environment
variables to the iOS simulator.

Fixes #20.

Author: jeffh

Fox/Public/FOXEnvironment.h

@@ -1,14 +1,22 @@
 #import "FOXMacros.h"
 
 /*! The default number of tests (which is 500).
- *  Can be overridden by FOX_NUM_TESTS environment variables.
  *
+ *  Can be overridden by FOX_NUM_TESTS environment variables or by
+ *  FOXSetNumberOfTests(). The environment variable superseeds the setter.
+ *
+ *  The setter is provided since iOS test bundles cannot be given environment
+ *  variables via the xcodebuild test command.
+ *
+ *  @seealso FOXSetNumberOfTests to use the setter.
  *  @returns the number of tests the default runner should create.
  */
 FOX_EXPORT NSUInteger FOXGetNumberOfTests(void);
 
 /*! The default maximum size of data generation for tests (default 200).
- *  Can be overridden by FOX_MAX_SIZE environment variable.
+ *
+ *  Can be overridden by FOX_MAX_SIZE environment variable or by
+ *  FOXSetMaximumSize(). The environment variable superseeds the setter.
  *
  *  The maximum size factor that generators will generate. A size value is generated
  *  by FOX as the size the generators in the properties use. The maximum size factor
@@ -19,15 +27,51 @@ FOX_EXPORT NSUInteger FOXGetNumberOfTests(void);
  *  the size indicates how large each element is (eg - large integers) AND how many
  *  elements are generated.
  *
+ *  The setter is provided since iOS test bundles cannot be given environment
+ *  variables via the xcodebuild test command.
+ *
+ *  @seealso FOXSetMaximumSize
  *  @returns the maximum size the default runner can generate for data in tests.
  */
 FOX_EXPORT NSUInteger FOXGetMaximumSize(void);
 
 /*! The default seed Fox uses to create data and run tests.
- *  Can be overridden by FOX_SEED environment variable.
+ *
+ *  Can be overridden by FOX_SEED environment variable or by FOXSetSeed. The
+ *  environment variable superseeds the setter.
  *
  *  The default will be the current time (using time(NULL)).
  *
+ *  The setter is provided since iOS test bundles cannot be given environment
+ *  variables via the xcodebuild test command.
+ *
  *  @returns the random seed the default runner will use.
  */
 FOX_EXPORT NSUInteger FOXGetSeed(void);
+
+/*! Sets the default number of tests to use.
+ *
+ *  Does not override setting the FOX_NUM_TESTS environment variable.
+ *
+ *  @param defaultNumberOfTests The number of tests to generate by default.
+ *  @seealso FOXGetNumberOfTests
+ */
+FOX_EXPORT void FOXSetNumberOfTests(NSUInteger defaultNumberOfTests);
+
+/*! Sets the default maximum size to use.
+ *
+ *  Does not override setting the FOX_MAX_SIZE environment variable.
+ *
+ *  @param defaultMaximumSize The maximum size hint Fox should use to generate data by default.
+ *  @seealso FOXGetMaximumSize
+ */
+FOX_EXPORT void FOXSetMaximumSize(NSUInteger defaultMaximumSize);
+
+/*! Sets the default random seed to use.
+ *
+ *  Does not override setting the FOX_SEED environment variable.
+ *
+ *  @param defaultRandomSeed The random seed to use when generating data by default.
+ *  @seealso FOXGetSeed
+ */
+FOX_EXPORT void FOXSetSeed(NSUInteger defaultRandomSeed);

Fox/Public/FOXEnvironment.m

@@ -1,9 +1,12 @@
 #import "FOXEnvironment.h"
 
-
 const NSUInteger FOXDefaultNumberOfTests = 500;
 const NSUInteger FOXDefaultMaximumSize = 200;
 
+static NSUInteger __FOXNumberOfTests = FOXDefaultNumberOfTests;
+static NSUInteger __FOXMaximumSize = FOXDefaultMaximumSize;
+static NSUInteger __FOXSeed = 0;
+
 static NSUInteger FOXGetUIntegerFromEnv(const char *envname, NSUInteger defaultValue) {
     const char *envval = getenv(envname);
     unsigned long number = defaultValue;
@@ -13,18 +16,42 @@ static NSUInteger FOXGetUIntegerFromEnv(const char *envname, NSUInteger defaultV
     return (NSUInteger)number;
 }
 
-FOX_EXPORT NSUInteger FOXGetNumberOfTests(void) {
-    return FOXGetUIntegerFromEnv("FOX_NUM_TESTS", FOXDefaultNumberOfTests);
+static NSUInteger FOXEnsureNonZero(NSUInteger value, NSUInteger defaultValue) {
+    if (value == 0) {
+        return defaultValue;
+    } else {
+        return value;
+    }
+}
+
+NSUInteger FOXGetNumberOfTests(void) {
+    return FOXEnsureNonZero(FOXGetUIntegerFromEnv("FOX_NUM_TESTS", __FOXNumberOfTests),
+                            FOXDefaultNumberOfTests);
+}
+
+NSUInteger FOXGetMaximumSize(void) {
+    return FOXEnsureNonZero(FOXGetUIntegerFromEnv("FOX_MAX_SIZE", __FOXMaximumSize),
+                            FOXDefaultNumberOfTests);
+}
+
+NSUInteger FOXGetSeed(void) {
+    if (!__FOXSeed) {
+        __FOXSeed = (NSUInteger)time(NULL);
+    }
+    return FOXGetUIntegerFromEnv("FOX_SEED", __FOXSeed);
+}
+
+void FOXSetNumberOfTests(NSUInteger defaultNumberOfTests) {
+    __FOXNumberOfTests = defaultNumberOfTests;
 }
 
-FOX_EXPORT NSUInteger FOXGetMaximumSize(void) {
-    return FOXGetUIntegerFromEnv("FOX_MAX_SIZE", FOXDefaultMaximumSize);
+void FOXSetMaximumSize(NSUInteger defaultMaximumSize) {
+    __FOXMaximumSize = defaultMaximumSize;
 }
 
-FOX_EXPORT NSUInteger FOXGetSeed(void) {
-    static NSUInteger ___seed;
-    if (!___seed) {
-        ___seed = FOXGetUIntegerFromEnv("FOX_SEED", (NSUInteger)time(NULL));
+void FOXSetSeed(NSUInteger defaultRandomSeed) {
+    if (defaultRandomSeed == 0) {
+        defaultRandomSeed = (NSUInteger)time(NULL);
     }
-    return ___seed;
+    __FOXSeed = defaultRandomSeed;
 }

docs/source/runner.rst

@@ -23,18 +23,18 @@ three parameters to configure Fox's test generation:
 
 - The **seed** allows you to seed the random number generator Fox uses. This
   allows you to set the PRNG to help reproduce failures that Fox may have
-  generated during a test run.  Setting this to the default (``0``) will make
+  generated during a test run.  Setting this to the default (``0``) makes
   Fox generate a seed based on the current time.
-- The **number of tests** indicates the number of tests Fox will generate for
+- The **number of tests** indicates the number of tests Fox generates for
   this particular property. More tests generated will more thoroughly cover the
-  property at the cost of time. Setting this to the default (``0``) will make
+  property at the cost of time. Setting this to the default (``0``) makes
   Fox run ``500`` tests.
-- The **maximum size** indicates the maximum size factor Fox will use when
+- The **maximum size** indicates the maximum size factor Fox uses when
   generating tests. Generators use this size factor as a hint to produce data
-  of the appropriate sizes. For example, ``FOXInteger`` will generate integers
-  within the range of 0 to ``maximumSize`` and ``FOXArray`` will generate
+  of the appropriate sizes. For example, ``FOXInteger`` generates integers
+  within the range of 0 to ``maximumSize`` and ``FOXArray`` generates
   arrays whose number of elements are in the range of 0 to ``maximumSize``.
-  Setting this to the default (``0``) will make Fox run with a ``maximumSize``
+  Setting this to the default (``0``) makes Fox run with a ``maximumSize``
   of ``200``.  If you know this property's data generation can tolerate larger
   sizes, feel free to increase this. Large collection generation can be
   prohibitively expensive.
@@ -45,8 +45,8 @@ be recorded to reproduce a failure that Fox may have generated.
 Per Assertion Configuration
 ---------------------------
 
-By default, Fox will generate **500 tests per assertion** with a **maximum size
-of 200** and a random seed. By changing ``FOXAssert`` to ``FOXAssertWithOptions``
+By default, Fox generates **500 tests per assertion** with a **maximum size of
+200** and a random seed. By changing ``FOXAssert`` to ``FOXAssertWithOptions``
 we can provide optional configuration by using the ``FOXOptions``::
 
     FOXAssertWithOptions(FOXForAll(...), (FOXOptions){
@@ -61,14 +61,60 @@ Global Configuration
 Values can be overridden using `environment variables`_ to globally change the
 defaults.
 
+.. note:: Note that as of this time of writing, ``xcodebuild test`` (command
+          line) does not properly pass environment variables to test bundles
+          for iOS. Use the setter style listed after the environment variables
+          instead.
+
+          It is fine to set environment variables via Xcode.
+
 - Setting ``FOX_SEED`` can specify a specific seed to run for all properties.
 - Setting ``FOX_NUM_TESTS`` sets the number of tests to generate for each
   property.
-- Setting ``FOX_MAX_SIZE`` sets the maximum size factor Fox will use to when
+- Setting ``FOX_MAX_SIZE`` sets the maximum size factor Fox uses to when
   generating tests.
 
 .. _environment variables: http://nshipster.com/launch-arguments-and-environment-variables/
 
+If you cannot use environment variables, Fox also allows you to manually
+override the values via setters:
+
+- ``FOXSetSeed(NSUInteger seed)`` sets the random seed.
+- ``FOXSetNumberOfTests(NSUInteger numTests)`` sets the number of tests.
+- ``FOXSetMaximumSize(NSUInteger maxSize)`` sets the maximum size.
+
+An easy way to use these setters would be in an ``+[initialize]``  or ``+[load]`` method::
+
+    @interface TestHelper : NSObject
+    @end
+
+    @implementation TestHelper
+
+    + (void)initialize {
+      if (self == [TestHelper class]) {
+        FOXSetNumberOfTests(200);
+        FOXSetMaximumSize(50);
+      }
+    }
+
+    @end
+
+Using compile-time settings or macros, you can conditionally customize the
+values as needed.
+
+Configuration Priority
+----------------------
+
+Even though Fox accepts many different ways of setting global configuration,
+there is a specific ordering Fox checks for configuration values.
+
+The priority that Fox takes for these configurations are in order:
+
+1. The per-assertion configuration if provided.
+2. The environment variable overrides if provided.
+3. The setter function values are used if provided.
+4. Fox's internal default values are used.
+
 .. _Random Number Generators:
 
 Random Number Generators