Siesta Specs

Report generated from regression tests. Click a spec to see the code on Github.

See also: Siesta Overview | User Guide | API Docs

• Service
  • init()
    • enforces a trailing slash on baseURL
    • preserves baseURL query parameters
    • supports baseURL as String
    • supports baseURL as URL
    • with no baseURL
      • returns a nil baseURL
      • fails all requests for path-based resources
      • allows requests for absolute URLs
    • with an invalid baseURL
      • returns a nil baseURL
      • fails all requests for path-based resources
      • allows requests for absolute URLs
  • resource(_:)
    • returns a resource that belongs to this service
    • resolves all strings as subpaths of baseURL, interposing a slash if needed
    • does not apply special interpretation to . or ..
    • does not apply special interpretation to // or protocol://
    • escapes all characters as part of the path (even ones that look like query strings)
    • preserves baseURL query params
  • resource(baseURL:path:)
    • ignores the service’s baseURL
    • interposes a slash if needed
    • escapes all characters as part of the path
  • resource(absoluteURL:)
    • returns a resource with the given String URL
    • returns a resource with the given URL
    • ignores baseURL
    • gives a non-nil but invalid resource for invalid URLs
  • caching
    • gives the same Resource instance for the same path
    • gives the same Resource instance no matter how it’s constructed
    • releases unused resources on low memory events
    • releases unused resources on call to flushUnusedResource()
    • releases unused resources when cache limit exceeded
  • configuration
    • using regexps
      • matches substrings
      • matches the entire URL
      • respects regexp options
    • allows config blocks to be named for logging purposes
    • passes default configuration through if not overridden
    • applies resource-specific config only to that resource
    • applies predicate config only to matching resources
    • applies request config only to matching request methods
    • changes when service config added
    • changes when invalidateConfiguration() called
    • is not computed when traversing resources but not using them
    • using wilcards
      • handles service with no baseURL
      • matches full URLs
      • can match host and port separately
      • ignores a leading slash
      • matches path segments with *
      • matches across segments with **
      • matches single non-separator chars with ?
      • ignores query strings in the matched URL
      • matches against the base URL
    • applies global config to all resources
  • wipeResources()
    • wipes all resources by default
    • can wipe a specific resource
    • wipes only resources matching a pattern
    • wipes only resources matched by predicate
• Resource paths
  • child()
    • returns a resource with the same service
    • resolves empty string as root
    • resolves bare paths as subpaths
    • resolves paths with / prefix as subpaths
    • does not resolve ./ or ../
    • treats URL-like strings as paths
    • escapes characters when necessary
  • relative()
    • allows duplicate param keys in supplied query string
    • treats bare paths as if they are preceded by ./
    • resolves ./
    • resolves ../
    • resolves absolute paths relative to host root
    • resolves full URLs
    • can add a query string
    • does not alphabetize query string params, unlike withParam(_:_:)
    • entirely replaces or removes an existing query string
    • returns a resource with the same service
  • optionalRelative()
    • works like relative() if arg is present
    • returns nil if arg is absent
  • withParam()
    • allows parameter alteration and removal via dictionary
    • escapes params
    • alphabetizes params (to help with resource uniqueness)
    • modifies existing params without affecting others
    • treats empty string value as empty param
    • treats nil value as removal
    • drops query string if all params removed
    • accepts multiple parameters as a dictionary
    • adds params
• Resource observers
  • observer
    • with multiple owners
      • is not removed if self-ownership is not removed
      • is not removed if external owner is not removed
      • is removed when all owners are removed
    • receives a notification that it was removed
    • receives removal notification if not externally retained but not self-owned
    • does not receive removal notification if self-owned and not externally retained
    • receives a notification every time it is removed and re-added
    • is unaffected by removeObservers() with nil owner
    • is chainable
    • receives request event
    • receives new data event
    • receives new data event from local override
    • receives not modified event
    • receives error if server sends not modified but no local data
    • receives cancel event
    • receives failure event
    • does not receive notifications for request(), only load()
    • can be a closure
    • can have multiple closure observers
    • is not added twice if it is an object
    • receives a notification that it was added
  • resource memory management
    • prevents the resource from being deallocated while it has observers
    • allows resource deallocation when no observers left
    • allows resource deallocation when observer owners are deallocated
    • re-retains resource when observers added again
    • reeastablishes strong observer ref when owner re-added
  • observer auto-removal
    • stops observing when self-owned observer is deallocated
    • stops observing when owner is deallocated
• Response data handling
  • plain text handling
    • via .text convenience
      • gives a string
      • gives empty string for non-text response
      • gives empty string on error
    • parses text/foo as text
    • defaults to ISO-8859-1
    • handles UTF-8
    • handles more unusual charsets
    • treats an unknown charset as an errors
    • treats illegal byte sequence for encoding as an error
    • reports an error if another transformer already made it a string
    • transforms error responses
    • does not parse everything as text
    • parses text/plain as text
  • JSON handling
    • via .jsonArray convenience
      • gives JSON data
      • gives empty dict for non-dict response
    • parses application/foo+json as JSON
    • parses foo/json as JSON
    • does not parse everything as JSON
    • reports JSON parse errors
    • treats top-level JSON that is not a dictionary or array as an error
    • can parse JSON atoms with custom configuration
    • transforms error responses
    • preserves root error if error response is unparsable
    • can log JSON-like container with non-JSON contents
    • via .jsonDict convenience
      • gives JSON data
      • gives empty dict for non-JSON response
      • gives empty dict on error
    • parses application/json as JSON
  • image handling
    • parses images
    • gives an error for unparsable images
  • standard transformers
    • include JSON, text
    • can be selectively disabled on Service creation
    • can be cleared and re-added in configuration
  • custom transformer
    • using ResponseTransformer protocol
      • can transform data
      • can transform errors
      • does not reprocess existing data on 304
      • can modify headers
    • using closure
      • that returns an optional
        • can return nil to signal failure
        • can return a value to signal success
      • leaves errors untouched by default
      • can transform errors
      • can throw a custom error
      • can throw a RequestError
      • replaces previously configured model transformers by default
      • can append to previously configured model transformers
      • can be limited to specific HTTP request methods
      • with mismatched input type
        • treats it as an error by default
        • skips the transformer on .Skip
        • can skip the transformer with .SkipIfOutputTypeMatches
        • can flag output type mistmatch with .SkipIfOutputTypeMatches
      • can transform data
  • typedContent()
    • returns content if present
    • returns default if no content
    • returns default if content present but wrong type
    • can handle optional defaults
    • does not evaluate default unless needed
• Progress
  • always reaches 1
    • on success
    • on request error
    • on server error
    • on connection error
    • on cancellation
  • computation
    • for request with no body
      • increases while waiting for request to start
      • is stable when response arrives
      • tracks download
      • tracks download even when size is unknown
      • never reaches 1 if response size is unknown
      • is stable when estimated download size becomes precise
      • does not exceed 1 even if bytes downloaded exceed total
    • for request with a body
      • tracks download
      • tracks upload
      • tracks upload even if upload size is unknown
      • is stable when estimated upload size becomes precise
      • does not track time while uploading
      • increases while waiting for response after upload
      • is stable when response arrives
      • is stable when request starts uploading after a delay
  • callback
    • receives periodic updates during request
    • last notification
      • is 1
      • comes before the completion callback
• Weak cache
  • get()
    • returns a newly created instance
    • returns the same instance on the second fetch
    • does not call the cache miss block on the second fetch
    • returns different instances for different keys
  • flushUnused()
    • discards unused instances
    • holds on to retained instances
    • responds to low memory events
  • entryCountLimit
    • flushes unused entried when exceeded
    • does not flush entries still in use
    • flushes entries if lowered below current count
• Resource state
  • wipe()
    • clears latestData
    • clears latestError
    • cancels all requests in progress and prevents them from updating resource state
    • cancels requests attached with load(using:) even if they came from another resource
  • request()
    • does not update the resource state
    • tracks concurrent requests
  • load()
    • receiving an etag
      • stores the etag
      • sends the etag with subsequent requests
      • handles subsequent 200 by replacing data
      • handles subsequent 304 by keeping existing data
    • stores the response data
    • stores the content type
    • extracts the charset if present
    • includes the charset in the content type
    • parses the charset
    • defaults content type to raw binary
    • stores headers
    • handles missing etag
    • handles request errors
    • treats HTTP 400 as an error
    • treats HTTP 401 as an error
    • treats HTTP 402 as an error
    • treats HTTP 403 as an error
    • treats HTTP 404 as an error
    • treats HTTP 405 as an error
    • treats HTTP 406 as an error
    • treats HTTP 407 as an error
    • treats HTTP 408 as an error
    • treats HTTP 409 as an error
    • treats HTTP 410 as an error
    • treats HTTP 500 as an error
    • treats HTTP 501 as an error
    • treats HTTP 502 as an error
    • treats HTTP 503 as an error
    • treats HTTP 504 as an error
    • treats HTTP 505 as an error
    • preserves last valid data after error
    • leaves everything unchanged after a cancelled request
    • generates error messages from NSError message
    • generates error messages from HTTP status codes
    • marks that the resource is loading
  • loadIfNeeded()
    • loads a resource never before loaded
    • returns the existing request if one is already in progress
    • initiates a new request if a non-load request is in progress
    • with data present
      • does not load again soon
      • loads again later
      • respects custom expiration time
    • with an error present
      • does not retry soon
      • retries later
      • respects custom retry time
  • load(using:)
    • updates resource state
    • notifies observers
  • cancelLoadIfUnobserved()
    • cancels if resource has no observers
    • does not cancel if resource has an observer
    • cancels multiple load requests
    • (afterDelay:)
      • cancels load if resource loses its observers during delay
      • does not cancel load if resource gains an observer during delay
      • cancels load after the delay
      • does not cancel load before the delay
  • overrideLocalData()
    • updates the data
    • clears the latest error
    • does not touch the transformer pipeline
  • overrideLocalContent()
    • updates latestData’s content without altering headers
    • updates latestData’s timestamp
    • creates new application/binary entity if latestData is nil
  • invalidate()
    • does not trigger an immediate request
    • causes loadIfNeeded() to trigger a request
    • still affects the next loadIfNeeded() if load cancelled
    • leaves latestData and latestError intact
    • leaves timestamps intact
    • only affects loadIfNeeded() once
      • if loadIfNeeded() succeeds
      • if loadIfNeeded() fails
      • if load() completes
      • if local*Override() called
  • starts in a blank state
• Request
  • with custom delegate
    • doesn't automatically start
    • doesn't complete until completion handler called
    • yields the response from the completion handler
    • will ignore the response after one is already broadcast
  • .cancel() has no effect if it already succeeded
  • .cancel() has no effect if it never started
  • Resource.request()
    • initates a network call
    • handles various HTTP methods
    • represents response without body as zero-length Data for head → 200
    • represents response without body as zero-length Data for post → 204
    • sends headers from configuration
    • mutators
      • can alter headers
      • can read and alter the body
      • can alter the HTTP method, but this does not change mutators used
    • decorators
      • are called for every request
      • can attach request hooks
      • can preemptively cancel requests
      • substituting a request
        • causes outside observers to see the replacement
        • causes downstream decorators to see the replacement
        • does not start the original request if it was discarded
        • starts the original request if it is the first in a chain
        • runs the original request if it is deferred but used by a chain
        • does not run the original request if it is unused by a chain
  • repeated()
    • does not send the repeated request automatically
    • sends a new network request on start()
    • leaves the old request’s result intact
    • does not call the old request’s callbacks
    • picks up header config changes
    • repeats custom response mutation
    • does not repeat request decorations
  • request body generation
    • with URL encoding
      • encodes parameters
      • escapes unsafe characters
      • gives request failure for unencodable strings
    • handles string data
    • handles string encoding errors
    • handles JSON data
    • handles JSON encoding errors
    • overrides any Content-Type set in configuration headers
    • lets ad hoc request mutation override the Content-Type
    • lets configured mutators override the Content-Type
    • handles raw data
  • chained()
    • it can use the wrapped request’s response
    • it can use a custom response
    • it can chain to a new request
    • it can repeat the request
    • isCompleted is false until a “use” action
    • cancel()
      • cancels the underlying request
      • stops the chain from proceeding
      • does not stop the chain if the underlying request is cancelled
    • repeated()
      • repeats the wrapped request
      • reruns the chain’s logic afresh
      • does not rerun chained requests wrapped outside of the restart
  • can be cancelled
• Pipeline
  • can clear previously configured transformers
  • stage order
    • determines transformer order
    • can reorder transformers already added
    • will skip unlisted stages
    • supports custom keys
  • individual stage
    • runs transformers in the order added
    • can clear and replace transformers
• Entity cache
  • can specify a custom workQueue
  • can opt out by returning a nil key
  • read
    • loadIfNeeded() called multiple times
      • waits for cache hit before proceeding to network
      • after populated from cache, does not use network if data is fresh
      • proceeds to network on cache miss
      • proceeds to network if cached data is stale
    • leaves resource empty if no cached data
    • ignores cached data if latestData populated before cache read completes
    • prefers cache hits from later stages
    • processes cached content with the subsequent stages’ transformers
    • skips cached content that fails subsequent transformation
    • loadIfNeeded() called once
      • waits for cache hit before proceeding to network
      • after populated from cache, does not use network if data is fresh
      • proceeds to network on cache miss
      • proceeds to network if cached data is stale
    • returns an empty resource, then populates cached content
  • write
    • caches new data on success
    • writes each stage’s output to that stage’s cache
    • does not cache errors
    • updates cached data timestamp on 304
    • clears cached data on local override