https://www.rwx.com/docs/_next/static/chunks/pages/abq/running-locally-504570f5fca1fe94.js

1(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[4685],{7424:(e,n,r)=>{"use strict";r.r(n),r.d(n,{__N_SSG:()=>l,default:()=>i});var s=r(37876),o=r(91668);function t(e){let n={a:"a",code:"code",h1:"h1",h2:"h2",li:"li",p:"p",pre:"pre",ul:"ul",...(0,o.R)(),...e.components},{Note:r}=n;return r||function(e,n){throw Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Note",!0),(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.h1,{id:"running-abq-locally",children:"Running ABQ locally"}),"\n",(0,s.jsx)(n.p,{children:"You can install ABQ locally on OS X using Homebrew."}),"\n",(0,s.jsx)(n.pre,{code:"brew install rwx-research/tap/abq\n",children:(0,s.jsx)(n.code,{children:"brew install rwx-research/tap/abq\n"})}),"\n",(0,s.jsxs)(n.p,{children:["We do not currently have packages available for other operating systems.\nPlease ",(0,s.jsx)(n.a,{href:"https://www.rwx.com/support",children:"let us know"})," if you'd like to install ABQ locally on Linux."]}),"\n",(0,s.jsx)(n.h2,{id:"test-framework-integration",children:"Test framework integration"}),"\n",(0,s.jsxs)(n.p,{children:["To run ABQ locally, you'll need to ",(0,s.jsx)(n.a,{href:"/abq/getting-started#test-frameworks",children:"configure your test framework"})," using\nthe same configuration you need when running ABQ on CI."]}),"\n",(0,s.jsx)(n.h2,{id:"example-cli-usage",children:"Example CLI usage"}),"\n",(0,s.jsx)(n.p,{children:"Once your test framework is configured, you can use ABQ to parallelize your test suite when running it locally."}),"\n",(0,s.jsxs)(n.p,{children:["Although ABQ is designed to run in a distributed network, when running the ",(0,s.jsxs)(n.a,{href:"/abq/cli-reference/test",children:[(0,s.jsx)(n.code,{children:"abq test"})," command"]})," locally, ABQ will start an\nephemeral queue and one or more workers locally.\nThe command can be invoked with any native test command, similar to ",(0,s.jsx)(n.a,{href:"/abq/getting-started",children:"how its used on CI"}),"."]}

1),"\n",(0,s.jsx)(n.pre,{code:"abq test -- any test command goes here\n",children:(0,s.jsx)(n.code,{children:"abq test -- any test command goes here\n"})}),"\n",(0,s.jsx)(n.p,{children:"For example with RSpec:"}),"\n",(0,s.jsx)(n.pre,{code:"abq test -- bundle exec rspec\n",children:(0,s.jsx)(n.code,{children:"abq test -- bundle exec rspec\n"})}),"\n",(0,s.jsxs)(n.p,{children:["By default, ",(0,s.jsx)(n.code,{children:"abq test"})," will only run a single worker. You can set the number of workers by passing the ",(0,s.jsx)(n.code,{children:"-n"})," option. For example, to run two workers:"]}),"\n",(0,s.jsx)(n.pre,{code:"abq test -n 2 -- any test command goes here\n",children:(0,s.jsx)(n.code,{children:"abq test -n 2 -- any test command goes here\n"})}),"\n",(0,s.jsxs)(n.p,{children:["If you'd like to run one worker per CPU core available, you can pass ",(0,s.jsx)(n.code,{children:"-n cpu-cores"}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["You can see a full list of commands by running ",(0,s.jsx)(n.code,{children:"abq help"})," and a full list of arguments to ",(0,s.jsx)(n.code,{children:"abq test"})," by running ",(0,s.jsx)(n.code,{children:"abq test --help"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"worker-number-environment-variable",children:"Worker number environment variable"}),"\n",(0,s.jsxs)(n.p,{children:["Depending on your native test suite, you may need an environment variable to differentiate test processes.\nFor example, it's common in some frameworks to set up separate databases for each parallel test process.\nABQ will set an ",(0,s.jsx)(n.code,{children:"ABQ_RUNNER"})," environment variable that contains an integer sequence starting from 1."]}),"\n",(0,s.jsxs)(n.p,{children:["For example, in a project that needs ",(0,s.jsx)(n.code,{children:"TEST_ENV_NUMBER"})," set to run tests in parallel, ABQ can be invoked like this:"]}),"\n",(0,s.jsx)(n.pre,{code:"abq test -n 2 -- bash -c 'TEST_ENV_NUMBER=$ABQ_RUNNER bundle exec rspec'\n",children:(0,s.jsx)(n.code,{children:"abq test -n 2 -- bash -c 'TEST_ENV_NUMBER=$ABQ_RUNNER bundle exec rspec'\n"})}),"\n",(0,s.jsx)(r,{children:(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.code,{children:"ABQ_RUNNER"})," is set when ",(0,s.jsx)(n.code,{children:"abq test"})," invokes the command specified after ",(0,s.jsx)(n.code,{children:"--"}),".\nTherefore, to set another environment variable based on the value of\n",(0,s.jsx)(n.code,{children:"ABQ_RUNNER"}),", you need to wrap the specified command in another script or\nshell command, such as ",(0,s.jsx)(n.code,{children:"bash -c"}),". Without wrapping it, your shell would\nattempt to use ",(0,s.jsx)(n.code,{children:"ABQ_RUNNER"})," before it's been set by ",(0,s.jsx)(n.code,{children:"abq test"}),"."]})}),"\n",(0,s.jsx)(n.h2,{id:"replaying-tests-locally",children:"Replaying tests locally"}),"\n",(0,s.jsx)(n.p,{children:"Occasionally it's useful to replay a remote test run locally."}),"\n",(0,s.jsx)(n.p,{children:"We can achieve this by running ABQ with a personal access token.\nTo generate a personal access token, perform the following:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Navigate to your ",(0,s.jsx)(n.a,{href:"https://cloud.rwx.com/_/personal_access_tokens",children:"Personal Access Tokens settings page"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"https://cloud.rwx.com/_/login",children:"Log in"})," to RWX"]}),"\n",(0,s.jsx)(n.li,{children:'From the hamburger navigation menu, select "Manage user"'}),"\n",(0,s.jsx)(n.li,{children:'Click on "Personal Access Tokens" on the menu on the left'}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.li,{children:'Click "New Personal Access Token"'}),"\n",(0,s.jsx)(n.li,{children:"Choose the organization you'd like to scope your personal access token to (if there are multiple)"}),"\n",(0,s.jsx)(n.li,{children:'Enter a description, such as "Sally\'s GitHub Actions Token"'}),"\n",(0,s.jsx)(n.li,{children:'Click "Create personal access token"'}),"\n",(0,s.jsx)(n.li,{children:"Copy the Access Token"}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["You may provide the ",(0,s.jsx)(n.code,{children:"abq"})," command with your personal access token via the environment variable ",(0,s.jsx)(n.code,{children:"RWX_ACCESS_TOKEN"}),", as a\ncommand line flag ",(0,s.jsx)(n.code,{children:"--access-token"}),", or by using the ",(0,s.jsx)(n.code,{children:"abq login"})," command to store a local configuration file."]}),"\n",(0,s.jsxs)(n.p,{children:["After doing this, invoke ",(0,s.jsx)(n.code,{children:"abq test --run-id <EXISTING_RUN_ID> --worker <WORKER> --num <NUM>"})," to replay your remote run\non that worker and runner locally."]}),"\n",(0,s.jsxs)(n.p,{children:["Or, call ",(0,s.jsx)(n.a,{href:"/abq/cli-reference/report/list-tests",children:(0,s.jsx)(n.code,{children:"abq report list-tests --run-id <EXISTING_RUN_ID> --worker <WORKER> --num <NUM>"})})," to\nlist which tests were run in what order on that worker & runner."]})]})}var l=!0;function i(e={}){let{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(t,{...e})}):t(e)}},73940:(e,n,r)=>{(window.__NEXT_P=window.__NEXT_P||[]).push(["/abq/running-locally",function(){return r(7424)}])}},e=>{e.O(0,[636,6593,8792],()=>e(e.s=73940)),_N_E=e.O()}]);