How to set up @ref/@forceRef dependency correctly?

[alekdavisintel]

I am trying to understand the explanation at https://httpyac.github.io/guide/metaData.html#ref-and-forceref ("forceRef always call the other request. ref only calls if no response is cached"), but I cannot find the description of "cached". Are responses cached for each run (by run, I mean executing a single request, multiple requests, a file, a folder, or multiple folders)? Or are they cached until you reset the environment?

I am trying to figure out how to correctly set up dependencies between requests. Say, requests X, Y, and Z depend on request A. I can run requests X, Y, and Z individually or as a group, but regardless of how I run them, I need request A to be executed only once (during each run). So, the run sequences could be:

• A, X
• A, Y
• A, Z
• A, X, Y
• A, X, Z
• A, Y, Z
• A, X, Y, Z

It should NOT be:

• A, X, A, Y
• A, X, A, Z
• A, Y, A, Z
• A, X, A, Y, A, Z

I thought that @ref would do this, but if I used @ref A and run X only, A does not get executed (I need to explicitly include both A and X in the run) unless I reset the environment. If I use @forceRef A, then running X, Y, or Z will first execute A, but if I run a combination of X, Y, and Z, then A seems to get invoked for each one of them, and I do not want this (think of test dependency when A creates a new item and X, Y, and Z do various operations on it, such as GET, PATCH, DELETE).

Could you clarify how this works and what I need to do to set up a dependency for each test run? If caching is set for the lifetime of the environment until I manually reset it, is there a way to configure it to have caching only valid for a test run (again, a test run means a run of a single test or multiple tests)? Or maybe there is some other way to clear cache before each run? Programmatically?

And while we're at it, is there a way to clear all output windows (httpac - Log, httpyac - console, httpyac - Request, and possibly response and variables tabs) before each run? It's a bit tedious to clear them manually and if I do not then the outputs intermingle with the outputs from the previous runs and since there are no separators between them, it is hard to see what happened when.

[AnWeber]

but I cannot find the description of "cached"

depending on the context.

• When using the command line, only within the current call (no hard disk cache, only memory).
• When using vscode as long as the extension host lives, or a till a reset is called. Caching is in memory, and I just reuse variables of previous run. If a variable with same name as request exists, no call is executed
  • e.g ref.http
  • if variable json exists, request with name json is not executed again. The variables are only slightly hidden and only visible in a “Debug” view

I thought that @ref would do this, but if I used @ref A and run X only, A does not get executed
try my ref.http. It did work on my machine, in vscode

Could you clarify how this works and what I need to do to set up a dependency for each test run?

I did not consider resetting the environment and it is not currently implemented. It could be done manually now, because you can simply trigger the execute the other request using script. But it doesn't feel good. That might be a feature.

# @name json
GET https://httpbin.org/anything?id={{$guid}}

###
{{
  if(!this.json || this.TEST_RUNNER){
    await $httpyac.execute("json");
  }
}}
POST https://httpbin.org/anything
{{json.args.id}}

And while we're at it, is there a way to clear all output windows (httpac - Log, httpyac - console, httpyac - Request, and possibly response and variables tabs) before each run?

Yes would be possible. vscode has an API for this.

[alekdavisintel]

Ah, thank you so much for the detailed explanation. I think it is starting to make sense to me now and it is very helpful. It may explain why I'm struggling with the dependencies (as described in #297).

Just to make sure:

• Assuming there is a named request # @name myTest, we'll use myTest as the name for the illustration.
• The name myTest can be used as a variable; this variable is undefined (or is it null?) before the first invocation of the request; after the first invocation of the request the variable will no longer be undefined until one of the following: (1) environment is reset (via Command Palette: httpYac: Reset Environments), (2) VSCode instance is restarted, or (3) VSCode project is reloaded.
• If the request returns a JSON body, then the myTest variable will hold the JSON object properties; these properties will be reset after each invocation of the request, but unless the request is explicitly called again, all references to this variable (via the # @ref myTest meta tag) will refer to the copy of the variable cached after the first request invocation.
• If the request does not return a body (e.g., from a DELETE or PATCH method), then the myTest variable will not have the JSON properties after the request gets called, but it will still not be undefined (the variable will get reset back to the undefined condition only after one of the events outlined above).
• When using VSCode, if the myTest request is skipped (via $cancel or @disabled) but the myTest variable is set during a previous run, the variable will retain the properties from the last run; if the request never ran, then the myTest variable will be undefined.
• When using VSCode, requests explicitly selected for execution (e.g., via the send selected option) will always run (unless they are disabled or cancelled via $cancel or @disabled).
• Names of the requests must be unique within the execution scope (or the whole projects, i.e. all HTTP/REST files), not just within a single file. If files x.http, y.http and z.http all have requests named getUserById and dependencies on the getUserById request (# @ref getUserById) are set, it is impossible to know how these dependencies will be resolved and which request in x.http, y.http and z.http will set the getUserById variable value, since they all can be called and cached at some point.
• When running tests via CLI, the lifecycle scope is the immediate run (so, each CLI execution resets the environment) making dependencies a lot simpler.

Did I get it right?

[AnWeber]

The name of the request (# @name request

I should prevent the name request and response

I will proof read it tomorrow but you should be right. And instead using name I should have used the word id

[alekdavisintel]

I will change the name in the comment (didn't think abou the implicit request variable).

[alekdavisintel]

I edited my summary, so when you get a chance to verify, please comment if I got it right or not (no rush).

Yes, ability to reset environment on every run and/or clear all outputs would be wonderful. I am currently testing APIs from several vendors, and they do not always work as expected. So, my curent workflow is:

• Clear test results.
• Clear output for request.
• Clear output for console.
• Clear output for log.
• Clear response tab.
• Clear variables (if I have them open).
• Run tests, validate results, tweak code, repeat from top.

It would be helpful to not have to repeat the clear steps every time. This could be governed by settings.

Another improvements would be some sort of separators in the output windows to indicate beginning and end of each test run because as of now, it's very hard to find where the previous test run ended and the last one began.

And a very minor improvement would be to mark the skipped requests that met the disabled/cancelled criteria in the request output window. You can figure out which steps were skipped in the other output windows, but the request output does not mention them at all, which makes it a bit confusing for a novice (at this point, I think I have an idea why they get skipped but I was struggling with it for the past couple of weeks).

And another monor improvement would be to clear response tab before each run. I use a single response output file/tab because dealing with many response files is cumbersome, and it shows the output of the last invoked reponse, which is fine, but if the last request did not run (it was disabled or cancelled), then it still shows output from the last run giving an impression that a request was made, when it wasn't. It bit me a few times before I realized the behavior.